Welcome

欢迎来到CoinCatch API文档！点击这里直接开始

近期接口变更预告

编号	接口	上线日期	功能描述

更新日志

2024年03月14日 - 新增获取提币记录v2接口

2023年12月28日 - 新增现货行情相关接口 - 新增现货交易订单类相关接口

2023年05月25日

• API 文档上线

简介

API 简介

欢迎使用CoinCatch开发者文档！

此文档是CoinCatch API的唯一官方文档，CoinCatch API提供的功能会在此持续更新，请大家及时关注。

你可以通过点击上方菜单来切换获取不同业务的API，还可通过点击右上方的语言按钮来切换文档语言。

文档右侧是针对请求参数以及响应结果的示例。

更新关注

关于API新增、更新、下线等信息CoinCatch会提前发布公告进行通知，建议您关注和订阅我们的公告，及时获取相关信息。

联系我们

使用过程中如有问题或者建议，您可选择以下方式联系我们：

• 发送邮件至API@coincatch.com。

快速入门

接入准备

如需使用API ，请先登录网页端，完成API key的申请和权限配置，再据此文档详情进行开发和交易。

您可以点击 这里 创建 API Key。

每个用户可创建10组Api Key，每个Api Key可对应设置读取、交易两种权限。

权限说明如下：

• 读取权限：读取权限用于对数据的查询，例如：行情数据。
• 交易权限：交易权限用于下单、撤单等接口。
• 划转权限：划转权限用于在CoinCatch用户账户之间划转加密货币。
• 提币权限：提币权限用于从CoinCatch账户转出资产。请注意，您只能通过IP白名单提币。

创建成功后请务必记住以下信息：

• APIKey API交易的身份标识，随机算法生成。
• Secretkey 私钥，由系统随机生成，用于签名的生成。
• Passphrase 口令，由用户自己设定,需要注意的是，Passphrase忘记之后是无法找回的，需要重新创建APIKey。

接口类型

本章节主要将接口类型分以下两个方面：

• 公共接口
• 私有接口

公共接口

公共接口可用于获取配置信息和行情数据。公共请求无需认证即可调用。

私有接口

私有接口可用于订单管理和账户管理。每个私有请求必须使用规范的验证形式进行签名。

私有接口需要使用您的APIKey进行验证。

访问限制

本章节主要为访问限制：

• 429 当访问超过频率限制时，将返回状态429：请求太频繁。

Rest API

如果传入有效的APIKey 用APIKey限速；如果没有则拿公网IP限速。

限速规则：各个接口上有单独的说明，如果没有一般接口限速为 10次/秒。

API域名

您可以自行使用Rest API接入方式进行操作。

域名	REST API	建议使用
域名	https://api.coincatch.com	主域名

API公开参数

groupType(账单流水大类型)

字段	说明
deposit	充值
withdraw	提现
transaction	交易
transfer	划转
other	其他

bizType(账单流水业务类型)

字段	说明
deposit	充值
withdraw	提现
buy	买
sell	卖
deduction of handling fee	币币交易手续费抵扣
transfer-in	转入
transfer-out	转出
rebate rewards	返佣奖励
airdrop rewards	空投奖励
USDT contract rewards	USDT专业合约活动奖励
mix contract rewards	混合合约活动奖励
System lock	系统锁仓
User lock	用户锁仓

status(充提订单状态)

字段	说明
cancel	取消
reject	拒绝
success	成功
wallet-fail	钱包失败
wallet-processing	钱包处理中
first-audit	初审
recheck	复审
first-reject	初审拒绝
recheck-reject	复审拒绝

type(用户提币地址查询)

字段	说明
chain-on	链上
inner-transfer	内部地址

fromType,toType(转入类型，转出类型)

字段	说明
spot	接受转入转出多个币种
mix_usdt	只接受转入转出USDT
mix_usd	混合合约账户，只接受转入转出保证金币种，如BTC, ETH, EOS, XRP, USDC等

enterPointSource

字段	说明
WEB	WEB 客户端
APP	APP 客户端
API	API 客户端
SYS	SYS 客户端
ANDROID	ANDROID 客户端
IOS	IOS 客户端

accountType

字段	说明
EXCHANGE	现货
CONTRACT	U本位合约账户
USDT_MIX	USDT 合约账户
USD_MIX	USD 合约账户

API验证

发起请求

所有REST请求的header都必须包含以下key：

• ACCESS-KEY：API KEY作为一个字符串。
• ACCESS-SIGN：使用base64编码签名（请参阅签名消息）。
• ACCESS-TIMESTAMP：您请求的时间戳。
• ACCESS-PASSPHRASE：您在创建API KEY时设置的口令。
• Content-Type：统一设置为application/json。
• locale:支持多语言，如：中文(zh-CN),英语(en-US)

//Java
System.currentTimeMillis();

//python
import time
time.time_ns() / 1000000

//Golang
import (
  "time"
)
int64(time.Now().UnixNano()/1000000)

//Javascript
Math.round(new Date())

//PHP
microtime(true) * 1000;

签名

ACCESS-SIGN的请求头是对 timestamp + method.toUpperCase() + requestPath + "?" + queryString + body 字符串(+表示字符串连接)使用 HMAC SHA256 方法加密，通过BASE64 编码输出而得到的。

签名各字段说明

• timestamp：与 ACCESS-TIMESTAMP 请求头相同。
• method：请求方法(POST/GET)，字母全部大写。
• requestPath：请求接口路径。
• queryString：请求URL中(?后的请求参数)的查询字符串。
• body：请求主体对应的字符串，如果请求没有主体(通常为GET请求)则body可省略。

queryString为空时，签名格式

timestamp + method.toUpperCase() + requestPath + body

queryString不为空时，签名格式

timestamp + method.toUpperCase() + requestPath + "?" + queryString + body

举例说明

获取深度信息，以 btcusdt 为例:

• Timestamp = 1591089508404
• Method = "GET"
• requestPath = "/api/spot/v1/market/depth"
• queryString= "?symbol=btcusdt_spbl&limit=20"

生成待签名的字符串:

'1591089508404GET/api/spot/v1/market/depth?symbol=btcusdt_spbl&limit=20'

下单，以 btcusdt 为例:

• Timestamp = 1561022985382
• Method = "POST"
• requestPath = "/api/spot/v1/order/order"
• body = {"symbol":"btcusdt_spbl","quantity":"8","side":"buy","price":"1","orderType":"limit","clientOrderId":"CoinCatch#123456"}

生成待签名的字符串:

'1561022985382POST/api/spot/v3/order/order{"symbol":"btcusdt_spbl","size":"8","side":"buy","price":"1","orderType":"limit","clientOrderId":"CoinCatch#123456"}'

生成最终签名的步骤

第1步，将待签名字符串使用私钥secretkey进行hmac sha256加密

Signature = hmac_sha256(secretkey, Message)

第2步，对于Signature进行base64编码

Signature = base64.encode(Signature)

加密示例

Java

public static String generate(String timestamp, String method, String requestPath,
                                  String queryString, String body, String secretKey)
            throws CloneNotSupportedException, InvalidKeyException, UnsupportedEncodingException {

        method = method.toUpperCase();
        body = StringUtils.defaultIfBlank(body, StringUtils.EMPTY);
        queryString = StringUtils.isBlank(queryString) ? StringUtils.EMPTY : "?" + queryString;

        String preHash = timestamp + method + requestPath + queryString + body;
        System.out.println(preHash);
        byte[] secretKeyBytes = secretKey.getBytes(SignatureUtils.CHARSET);
        SecretKeySpec secretKeySpec = new SecretKeySpec(secretKeyBytes, SignatureUtils.HMAC_SHA256);
        Mac mac = (Mac) SignatureUtils.MAC.clone();
        mac.init(secretKeySpec);
        return Base64.getEncoder().encodeToString(mac.doFinal(preHash.getBytes(SignatureUtils.CHARSET)));
    }


public static void main(String[] args) throws Exception {
      String msg=generate("1659927638003","POST","/api/spot/v1/trade/orders" ,null,"{"symbol":"TRXUSDT_SPBL","side":"buy","orderType":"limit","force":"normal","price":"0.046317","quantity":"1212"}","");
      System.out.println(msg);
    }

Python

def sign(message, secret_key):
    mac = hmac.new(bytes(secret_key, encoding='utf8'), bytes(message, encoding='utf-8'), digestmod='sha256')
    d = mac.digest()
    return base64.b64encode(d)


def pre_hash(timestamp, method, request_path, body):
    return str(timestamp) + str.upper(method) + request_path + body



if __name__ == '__main__':
    signStr = sign(pre_hash('1659927638003', 'POST', '/api/spot/v1/trade/orders', str('{"symbol":"TRXUSDT_SPBL","side":"buy","orderType":"limit","force":"normal","price":"0.046317","quantity":"1212"}')), '')
    print(signStr)

请求交互

所有请求基于Https协议，POST 请求头信息中Content-Type 需要统一设置为: 'application/json'。

请求交互说明

• 请求参数：根据接口请求参数规定进行参数封装。
• 提交请求参数：将封装好的请求参数通过GET/POST方式提交至服务器。
• 服务器响应：服务器首先对用户请求数据进行参数安全校验，通过校验后根据业务逻辑将响应数据以JSON格式返回给用户。
• 数据处理：对服务器响应数据进行处理。

成功

HTTP状态码200表示成功响应，并可能包含内容。如果响应含有内容，则将显示在相应的返回内容里面。

常见错误码

• 400 Bad Request – Invalid request format 请求格式无效
• 401 Unauthorized – Invalid API Key 无效的API Key
• 403 Forbidden – You do not have access to the requested resource 请求无权限
• 404 Not Found 没有找到请求
• 429 Too Many Requests 请求太频繁被系统限流
• 500 Internal Server Error – We had a problem with our server 服务器内部错误
• 如果失败body带有错误描述信息

标准规范

时间戳

请求签名中的ACCESS-TIMESTAMP的单位是毫秒。请求的时间戳必须在API服务时间的30秒内，否则请求将被视为过期并被拒绝。 如果本地服务器时间和API服务器时间之间存在较大的偏差，那么我们建议您使用通过查询API服务器时间来更新http header。

限频规则

如果请求过于频繁系统将自动限制请求，并在http header中返回429 too many requests状态码。

• 公共接口：如行情接口，统一限频为2秒最多20个请求。
• 授权接口：通过apikey限制授权接口的调用，参考每个接口的限频规则限频。

请求格式

目前只有两种格式的请求方法：GET和POST

• GET: 参数通过queryString在路径中传输到服务器。
• POST: 参数按照json格式发送body传输到服务器。

RestAPI

基础配置接口

获取服务器时间

限速规则：20次/1s (IP)

HTTP请求

获取服务器时间

• GET /api/spot/v1/public/time 

请求示例

curl "https://api.coincatch.com/api/spot/v1/public/time"

返回数据：

{
    "code": "00000",
    "msg": "success",
    "data": 1622097118134
}

币种基础信息

限速规则：3次/1s (IP)

HTTP请求 获取平台所有币种信息

• GET /api/spot/v1/public/currencies

请求示例

curl "https://api.coincatch.com/api/spot/v1/public/currencies"

返回数据:

{
    "code":"00000",
    "msg":"success",
    "data":[
        {
            "coinId":"1",
            "coinName":"BTC",
            "transfer":"true",
            "chains":[
                {
                    "chain":"BTC",
                    "needTag":"false",
                    "withdrawable":"true",
                    "rechargeAble":"true",
                    "withdrawFee":"0.005",
                    "extraWithDrawFee":"0",
                    "depositConfirm":"1",
                    "withdrawConfirm":"1",
                    "minDepositAmount":"0.001",
                    "minWithdrawAmount":"0.001",
                    "browserUrl":"https://blockchair.com/bitcoin/testnet/transaction/"
                }
            ]
        }
    ]
}

返回值说明

返回字段	字段说明
coinId	币种id
coinName	币种名称
transfer	是否可以划转
chains
> chain	链名称
> needTag	是否需要tag
> withdrawable	是否可提现
> rechargeAble	是否可充值
> withdrawFee	提现手续费
> extraWithDrawFee	额外钱包收取
> depositConfirm	充值确认块数
> withdrawConfirm	提现确认块数
> minDepositAmount	最小充值数
> minWithdrawAmount	最小提现数
> browserUrl	区块浏览器地址

公共行情接口

获取某个Ticker信息

限速规则：20次/1s (IP)

HTTP请求 获取某个ticker信息

• GET /api/spot/v1/market/ticker

请求参数

参数名	参数类型	是否必须	描述
symbol	String	是	产品ID

请求示例

curl "https://api.coincatch.com/api/spot/v1/market/ticker?symbol=BTCUSDT_SPBL"

返回数据:

{
    "code": "00000",
    "msg": "success",
    "data": {
        "symbol": "BTCUSDT",
        "high24h": "24175.65",
        "low24h": "23677.75",
        "close": "24014.11",
        "quoteVol": "177689342.3025",
        "baseVol": "7421.5009",
        "usdtVol": "177689342.302407",
        "ts": "1660704288118",
        "buyOne": "24013.94",
        "sellOne": "24014.06",
        "bidSz": "0.0663",
        "askSz": "0.0119",
        "openUtc0": "23856.72",
        "changeUtc":"0.00301",
        "change":"0.00069"
    }
}

返回值说明

返回字段	字段说明
symbol	币对名称
high24h	24小时最高价
close	最新成交价
low24h	24小时最低价
quoteVol	计价币成交额
baseVol	基础币成交额
usdtVol	usdt成交额
buyOne	买一价
sellOne	卖一价
bidSz	买一量
askSz	卖一量
openUtc0	零时区 开盘价
ts	时间戳
changeUtc	UTC0时涨跌幅, 0.01表示1%
change	24小时涨跌幅, 0.01表示1%

获取全部Ticker信息

限速规则：20次/1s (IP)

HTTP请求

获取全部ticker信息

• GET /api/spot/v1/market/tickers

请求示例

curl "https://api.coincatch.com/api/spot/v1/market/tickers"

返回数据

{
    "code":"00000",
    "data":[
      {
        "symbol":"BTCUSDT",
        "high24h":"34413.1",
        "low24h":"34413.1",
        "close":"34413.1",
        "quoteVol":"0",
        "baseVol":"0",
        "usdtVol":"0",
        "buyOne":"0",
        "sellOne":"0",
        "bidSz": "0.0663",
        "askSz": "0.0119",
        "openUtc0": "23856.72",
        "ts":"1625125755277",
        "changeUtc":"0.00301",
        "change":"0.00069"
    }
    ],
    "msg":"success"
}

返回值说明

返回字段	字段说明
symbol	产品ID
high24h	24小时最高价
close	最新成交价
low24h	24小时最低价
ts	系统时间戳
baseVol	基础币量
quoteVol	计价币量
usdtVol	usdt币量
buyOne	买一价
sellOne	卖一价
bidSz	买一量
askSz	卖一量
openUtc0	零时区 开盘价
changeUtc	UTC0时涨跌幅, 0.01表示1%
change	24小时涨跌幅, 0.01表示1%

获取最近成交数据

限速规则：10次/1s (IP)

HTTP请求

获取最近的500条成交数据

• GET /api/spot/v1/market/fills

请求参数

参数名	参数类型	是否必须	描述
symbol	String	是	产品ID
limit	String	否	默认100，最大500

请求示例

curl "https://api.coincatch.com/api/spot/v1/market/fills?symbol=BTCUSDT_SPBL"

返回数据:

{
    "code":"00000",
    "msg":"success",
    "data":[
        {
            "symbol":"BTCUSDT_SPBL",
            "tradeId":"781698148534505473",
            "side":"buy",
            "fillPrice":"2.38735",
            "fillQuantity":"2470.6224",
            "fillTime":"1622097282536"
        },
        {
            "symbol":"BTCUSDT_SPBL",
            "tradeId":"781698140590493697",
            "side":"sell",
            "fillPrice":"2.38649",
            "fillQuantity":"3239.7976",
            "fillTime":"1622097280642"
        }
    ]
}

返回值说明

返回字段	字段说明
symbol	产品ID
tradeId	成交单id
side	交易方向
fillPrice	成交价格
fillQuantity	成交数量
fillTime	成交时间

获取成交数据

限速规则：10次/1s (IP)

HTTP请求

获取近30天成交数据，数据会按请求参数缓存10分钟，请修改endTime以获取最近的成交记录

• GET /api/spot/v1/market/fills-history

请求参数

参数名	参数类型	是否必须	描述
symbol	String	是	产品ID
limit	String	否	默认500，最大1000
tradeId	String	否	成交ID，返回小于指定'tradeId'的记录
startTime	String	否	startTime, ms
endTime	String	否	endTime, ms

请求示例

curl "https://api.coincatch.com/api/spot/v1/market/fills-history?symbol=btcusdt_spbl&limit=2&tradeId=1020221685304578123&startTime=1678965010861&endTime=1678965910861"

返回数据:

{
    "code":"00000",
    "msg":"success",
    "data":[
        {
            "symbol": "BTCUSDT_SPBL",
            "tradeId": "1020221668657385473",
            "side": "Sell",
            "fillPrice": "21341",
            "fillQuantity": "0.5985",
            "fillTime": "1678965721000"
        },
        {
            "symbol": "BTCUSDT_SPBL",
            "tradeId": "1020221660121976833",
            "side": "Buy",
            "fillPrice": "21341",
            "fillQuantity": "0.3119",
            "fillTime": "1678965719000"
        }
    ]
}

返回值说明

返回字段	字段说明
symbol	产品ID
tradeId	成交单id, 降序排列
side	交易方向, Sell/Buy
fillPrice	成交价格
fillQuantity	成交数量
fillTime	成交时间

获取K线数据

限速规则：20次/1s (IP)

HTTP请求 获取K线数据

• GET /api/spot/v1/market/candles

请求参数

参数名	参数类型	是否必须	描述
symbol	String	是	产品ID
period	String	是	K线的时间单位,粒度（取值参考如下列表)
after	String	否	ms,返回大于等于本时间之后的
before	String	否	ms,返回小于等于本时间之前的
limit	String	否	查询条数 默认100，最大1000

请求示例

curl "https://api.coincatch.com/api/spot/v1/market/candles?symbol=BTCUSDT_SPBL&period=1min&after=1659076670000&before=1659080270000&limit=100"

返回数据:

{
    "code":"00000",
    "msg":"success",
    "data":[
        {
            "open":"2.34517",
            "high":"2.34771",
            "low":"2.34214",
            "close":"2.34555",
            "quoteVol":"189631.101357091",
            "baseVol":"80862.6823",
            "usdtVol":"189631.101357091",
            "ts":"1622091360000"
        },
        {
            "open":"2.34391",
            "high":"2.34903",
            "low":"2.34391",
            "close":"2.34608",
            "quoteVol":"167725.002115681",
            "baseVol":"71479.3205",
            "usdtVol":"167725.002115681",
            "ts":"1622091420000"
        }
    ]
}

返回值说明

返回字段	字段说明
ts	系统时间戳
open	开盘价格
high	最高价格
low	最低价格
close	收盘价格
baseVol	交易币成交量
quoteVol	计价币成交量
usdtVol	usdt成交量

period

• 1min(1分钟)
• 5min(5分钟)
• 15min(15分钟)
• 30min(30分钟)
• 1h(1小时)
• 4h(4小时)
• 6h(6小时)
• 12h(12小时)
• 1day(1天)
• 3day (3天)
• 1week(1周)
• 1M (月线)
• 6Hutc (零时区 6小时线)
• 12Hutc (零时区12小时线)
• 1Dutc (零时区 1日线)
• 3Dutc (零时区 3日线)
• 1Wutc (零时区 周线)
• 1Mutc (零时区 月线)

获取历史K线数据

限速规则：20次/1s (IP)

HTTP请求 获取K线数据

• GET /api/spot/v1/market/history-candles

请求参数

参数名	参数类型	是否必须	描述
symbol	String	是	产品ID
period	String	是	K线的时间单位,粒度（取值参考如下列表)
endTime	String	是	ms,返回小于等于本时间之前的
limit	String	否	查询条数 默认100，最大200

请求示例

curl "https://api.coincatch.com/api/spot/v1/market/history-candles?symbol=BTCUSDT_SPBL&period=1min&endTime=1659080270000&limit=100"

返回数据:

{
    "code":"00000",
    "msg":"success",
    "data":[
        {
            "open":"2.34517",
            "high":"2.34771",
            "low":"2.34214",
            "close":"2.34555",
            "quoteVol":"189631.101357091",
            "baseVol":"80862.6823",
            "usdtVol":"189631.101357091",
            "ts":"1622091360000"
        },
        {
            "open":"2.34391",
            "high":"2.34903",
            "low":"2.34391",
            "close":"2.34608",
            "quoteVol":"167725.002115681",
            "baseVol":"71479.3205",
            "usdtVol":"167725.002115681",
            "ts":"1622091420000"
        }
    ]
}

返回值说明

返回字段	字段说明
ts	系统时间戳
open	开盘价格
high	最高价格
low	最低价格
close	收盘价格
baseVol	交易币成交量
quoteVol	计价币成交量
usdtVol	usdt成交量

period

• 1min(1分钟)
• 5min(5分钟)
• 15min(15分钟)
• 30min(30分钟)
• 1h(1小时)
• 4h(4小时)
• 6h(6小时)
• 12h(12小时)
• 1day(1天)
• 3day (3天)
• 1week(1周)
• 1M (月线)
• 6Hutc (零时区 6小时线)
• 12Hutc (零时区12小时线)
• 1Dutc (零时区 1日线)
• 3Dutc (零时区 3日线)
• 1Wutc (零时区 周线)
• 1Mutc (零时区 月线)

获取深度数据

限速规则：20次/1s

HTTP请求 获取深度数据

• GET /api/spot/v1/market/depth

请求示例

curl "https://api.coincatch.com/api/spot/v1/market/depth?symbol=BTCUSDT_SPBL&type=step0&limit=100"

返回数据

{
    "code":"00000",
    "msg":"success",
    "data":{
        "asks":[
            [
                "38084.5",
                "0.0039"
            ],
            [
                "38085.7",
                "0.0018"
            ],
            [
                "38086.7",
                "0.0310"
            ],
            [
                "38088.2",
                "0.5303"
            ]
        ],
        "bids":[
            [
                "38073.7",
                "0.4993000000000000"
            ],
            [
                "38073.4",
                "0.4500"
            ],
            [
                "38073.3",
                "0.1179"
            ],
            [
                "38071.5",
                "0.2162"
            ]
        ],
        "timestamp":"1622102974025"
    }
}

请求参数

参数名	参数类型	是否必须	描述
symbol	String	是	产品ID
type	String	是	默认：step0： 取值：step0，step1，step2，step3，step4，step5
limit	String	否	查询条数 默认150, 最大200

type: 统一向上取整 强制进一

• step0 正常显示
• step1 去掉一位小数
• step2 去掉两位小数
• step3 去掉三位小数
• step4 去掉三位小数 向上取整为5的倍数
• step5 去掉四位小数

示例 BTCUSDt priceScale 2 当前价格 39223.42

• step1 39223.5
• step2 39224.0
• step3 39230.0
• step4 39250.0
• step5 39300.0

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

获取合并深度数据

限速规则：20次/1s

HTTP请求 获取合并深度数据

• GET /api/spot/v1/market/merge-depth

请求参数

参数名	参数类型	是否必须	描述
symbol	String	是	产品ID
precision	String	否	价格精度，根据选择的精度作为步长返回累计深度，枚举值：scale0/scale1/scale2/scale3,scale0 不合并，默认值,一般情况下，scale1为交易对报价精度*10的合并深度,一般情况下，scale2为报价精度*100,一般情况下，scale3为报价精度*1000,一般情况下，0/1/2/3对应的精度以实际返回参数“scale”为准,每个交易对的报价精度都不一样，部分币对并没有scale 2，请求该币对不存在的scale将会按照最大scale处理。例：某个交易对只有scale 0/1，当请求scale2时自动降为scale1。
limit	String	否	固定档位枚举值：1/5/15/50/max，默认档位100，当实际深度不满足limit时，按实际档位返回，传入max返回该交易对的最大档位

请求示例

curl "https://api.coincatch.com/api/spot/v1/market/merge-depth?symbol=BTCUSDT_SPBL&precision=scale0&limit=5"

返回数据

{
  "code": "00000",
  "msg": "success",
  "requestTime": 1692761101932,
  "data": {
    "asks": [
      [
        0.00000881,
        1000000
      ],
      [
        0.00000900,
        1000000
      ],
      [
        0.00001010,
        1000000
      ],
      [
        0.00001020,
        1110000
      ],
      [
        0.00001030,
        110000
      ]
    ],
    "bids": [
      [
        0.00000870,
        130000
      ],
      [
        0.00000860,
        130000
      ],
      [
        0.00000850,
        130000
      ],
      [
        0.00000840,
        130000
      ],
      [
        0.00000830,
        130000
      ]
    ],
    "ts": "1692761101940",
    "scale": "0.00000001",
    "precision": "scale0",
    "isMaxPrecision": "NO"
  }
}

返回值说明

参数名	参数类型	字段说明
asks	Array	当前价位的所有买单,如["38084.5","0.5"] 中，"38084.5"代表深度价格，"0.5"代表基础币数量
bids	Array	当前价位的所有卖单
precision	String	当前档位,例：scale 1
scale	String	实际的精度值，例：0.1
isMaxPrecision	String	YES 表示当前已经是最大精度，NO 非最大精度
ts	String	当前深度对应的时间

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

钱包接口

划转

限速规则：5次/1s (uid)

HTTP请求

• POST /api/spot/v1/wallet/transfer-v2

请求参数

参数名	参数类型	是否必须	描述
fromType	String	是	转出账户类型
toType	String	是	转入账户类型
amount	String	是	划转金额
coin	String	是	划转币种
clientOid	String	否	用户自定义ID

• fromType, toType
  • spot 接受转入转出多个币种
  • mix_usdt 只接受转入转出USDT
  • mix_usd 混合合约账户，只接受转入转出保证金币种，如BTC, ETH, EOS, XRP, USDC等

fromType/toType限制说明

fromType	toType	说明
spot	spot	任意转
spot	mix_usdt	只接受 USDT
spot	mix_usd	如 BTC, ETH, EOS, XRP, USDC
mix_usdt	spot	只接受 USDT
mix_usdt	mix_usd	禁止
mix_usdt	mix_usdt	只接受 USDT
mix_usd	spot	如 BTC, ETH, EOS, XRP, USDC
mix_usd	mix_usdt	禁止
mix_usd	mix_usd	如 BTC, ETH, EOS, XRP, USDC

请求示例

curl -X POST "https://api.coincatch.com/api/spot/v1/wallet/transfer-v2" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"fromType": "spot","toType": "mix_usdt","amount": "100","coin": "USDT"}'

返回数据:

{
    "code":"00000",
    "msg":"success",
    "data": {
        "transferId":"123456",
        "clientOrderId":"x123"
    }
}

返回值说明

返回字段	字段说明
transferId	划转ID
clientOrderId	Client Order ID

• fromType, toType
  • spot 接受转入转出多个币种
  • mix_usdt 只接受转入转出USDT
  • mix_usd 混合合约账户，只接受转入转出保证金币种，如BTC, ETH, EOS, XRP, USDC等

获取充币地址

限速规则：5次/1s (uid)

HTTP请求

• GET /api/spot/v1/wallet/deposit-address

请求参数

参数名	参数类型	是否必须	描述
coin	String	是	币种
chain	String	是	链名称

请求示例

curl "https://api.coincatch.com/api/spot/v1/wallet/deposit-address?coin=USDT&chain=trc20" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

返回数据:

{
  "code": "00000",
  "msg": "success",
  "data": {
    "address": "1HPn8Rx2y6nNSfagQBKy27GB99Vbzg89wv",
    "chain": "BTC-Bitcoin",
    "coin": "BTC",
    "tag": "",
    "url": "https://btc.com/1HPn8Rx2y6nNSfagQBKy27GB99Vbzg89wv"
  }
}

返回值说明

返回字段	字段说明
address	充币地址
chain	链名称
coin	币种名称
tag	tag
url	区块链地址

提币

只是链上提币

限速规则：5次/1s (uid)

HTTP请求

• POST /api/spot/v1/wallet/withdrawal-v2

请求参数

参数名	参数类型	是否必须	描述
coin	String	是	币种
address	String	是	提币地址
chain	String	是	提币网路
tag	String	否	地址tag
amount	String	是	提币数量
remark	String	否	备注
clientOid	String	否	客户端自定义Id 唯一健

'address' 应该在提币的 address book 里

请求示例

curl -X POST "https://api.coincatch.com/api/spot/v1/wallet/withdrawal-v2" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"coin": "USDT","address": "TBQ2LGFysnqkscvKqLBxnVVVw7ohiDvbdZ","chain": "trc20","amount": "10"}'

返回数据:

{
  "code": "00000",
  "msg": "success",
  "data": {
    "orderId":888291686266343424",
    "clientOrderId":"123"
  }
}

返回值说明

返回字段	字段说明
orderId	订单ID
clientOrderId	client order ID

内部提币

内部提币 指双方用户都在CoinCatch平台

通过uid形式直接提币，不走链上，不需要传地址

限速规则：5次/1s (uid)

HTTP请求

• POST /api/spot/v1/wallet/withdrawal-inner-v2

请求参数

参数名	参数类型	是否必须	描述
coin	String	是	币种
toUid	String	是	收款方uid
amount	String	是	提币数量
clientOid	String	否	客户端自定义ID 唯一健

请求示例

curl -X POST "https://api.coincatch.com/api/spot/v1/wallet/withdrawal-inner-v2" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"coin": "USDT","toUid": "6314497154","amount": "10"}'

返回数据

{
  "code": "00000",
  "msg": "success",
  "data": {
    "orderId":888291686266343424",
    "clientOrderId":"123"
  }
}

返回值说明

返回字段	字段说明
orderId	订单ID
clientOrderId	client order ID

获取提币记录

限速规则：20次/1s

HTTP请求

• GET /api/spot/v1/wallet/withdrawal-list

请求参数

参数名	参数类型	是否必须	描述
coin	String	否	币种
clientOid	String	否	clientOid
startTime	String	是	开始时间 (时间戳 毫秒)
endTime	String	是	结束时间 (时间戳 毫秒)
pageNo	String	否	查询页数 默认1
pageSize	String	否	条数 默认20 最大100

请求示例

curl "https://api.coincatch.com/api/spot/v1/wallet/withdrawal-list?coin=USDT&clientOid=123&startTime=1659036670000&endTime=1659076670000&pageNo=1&pageSize=20" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

返回数据:

{
    "code": "00000",
    "msg": "success",
    "requestTime": 1654507973411,
    "data": [
        {
            "id": "912533114861326336",
            "txId": "912533114861326336",
            "coin": "USDT",
            "clientOid": "123",
            "type": "withdraw",
            "amount": "10.00000000",
            "status": "success",
            "toAddress": "7713789662",
            "fee": "0.00000000",
            "chain": "erc20",
            "confirm": "0",
            "tag": null,
            "cTime": "1653290769222",
            "uTime": "1653290769222"
        }
    ]
}

返回值说明

返回字段	字段说明
id	订单id
txId	提现交易id
coin	币种名称
clientOid	clientOid
type	提币类型
amount	数量
status	提币状态
toAddress	提币地址
fee	手续费
chain	提币网络
confirm	确认块数
tag	tag
cTime	创建时间
uTime	修改时间

• status
  • pending 待初审
  • pending_review 待复审
  • pending_fail 初审失败
  • pending_review_fail 复审失败
  • reject 拒绝
  • success 成功

获取提币记录v2

限速规则：20次/1s

HTTP请求

• GET /api/spot/v1/wallet/withdrawal-list-v2

请求参数

参数名	参数类型	是否必须	描述
coin	String	否	币种
clientOid	String	否	自定义订单ID。与订单ID二选一，当传入clientOid时直接查询此订单，忽略其他入参
orderId	String	否	订单ID。与clientOid二选一，当传入订单ID时直接查询此订单，忽略其他入参
startTime	String	是	开始时间 (时间戳 毫秒)
endTime	String	是	结束时间 (时间戳 毫秒)
idLessThan	String	否	游标ID 用于翻页，首次查询不传，查询第二页及后面的数据时，取上一次查询返回的最小orderId，结果会返回小于该值的数据；可以缩短查询响应时间
limit	String	否	每页条目数 默认值为20，最大值为100

请求示例

curl "https://api.coincatch.com/api/spot/v1/wallet/withdrawal-list-v2?coin=USDT&clientOid=123&startTime=1659036670000&endTime=1659076670000" \
-H "ACCESS-KEY:you apiKey" \
-H "ACCESS-SIGN:*******" \
-H "ACCESS-PASSPHRASE:*****" \
-H "ACCESS-TIMESTAMP:1659076670000" \
-H "locale:en-US" \
-H "Content-Type: application/json"

返回数据:

{
"code": "00000",
"msg": "success",
"requestTime": 1654507973411,
"data": [
{
    "orderId": "912533114861326336",
    "tradeId": "912533114861326336",
    "coin": "USDT",
    "clientOid": "123",
    "type": "withdraw",
    "size": "10.00000000",
    "status": "success",
    "toAddress": "7713789662",
    "fee": "0.00000000",
    "chain": "erc20",
    "confirm": "0",
    "tag": null,
    "fromAddress": "0xxxxxxxxxxxxxxxxxxx",
    "dest": "on_chain",
    "cTime": "1653290769222",
    "uTime": "1653290769222"
}
]
}

返回值说明

返回字段	字段说明
orderId	订单id
tradeId	提现交易id
coin	币种名称
clientOid	clientOid
type	提币类型
size	数量
status	提币状态
toAddress	提币地址
fee	手续费
chain	提币网络
confirm	确认块数
tag	tag
dest	提币方式 on_chain: 链上提币 internal_transfer: 内部转账 inner_address_transfer: 内部地址转账
fromAddress	coin-raising
cTime	创建时间
uTime	修改时间

获取充值记录

限速规则：20次/1s

HTTP请求

• GET /api/spot/v1/wallet/deposit-list

请求参数

参数名	参数类型	是否必须	描述
coin	String	否	币种
startTime	String	是	开始时间 (时间戳 毫秒)
endTime	String	是	结束时间 (时间戳 毫秒)
pageNo	String	否	查询页数 默认1
pageSize	String	否	条数 默认20 最大100

请求示例

curl "https://api.coincatch.com/api/spot/v1/wallet/deposit-list?coin=USDT&startTime=1659036670000&endTime=1659076670000&pageNo=1&pageSize=20" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

返回数据:

{
    "code": "00000",
    "msg": "success",
    "requestTime": 1654507973411,
    "data": [
        {
            "id": "912533114861326336",
            "txId": "912533114861326336",
            "coin": "USDT",
            "type": "withdraw",
            "amount": "10.00000000",
            "status": "success",
            "toAddress": "7713789662",
            "fee": "0.00000000",
            "confirm":"10",
            "chain": "erc20",
            "tag": null,
            "cTime": "1653290769222",
            "uTime": "1653290769222"
        }
    ]
}

返回值说明

返回字段	字段说明
id	订单id
txId	交易id
coin	币种名称
type	充币类型
amount	数量
status	提币状态
toAddress	充值地址
fee	手续费
confirm	confirm, 可能为null
chain	充币网络
tag	tag
cTime	创建时间
uTime	修改时间

• status
  • Pending 待初审
  • pending_review 待复审
  • pending_fail 初审失败
  • pending_review_fail 复审失败
  • reject 拒绝
  • success 成功

账户接口

获取ApiKey信息

限速规则：1次/1s

HTTP请求

• GET /api/spot/v1/account/getInfo

请求示例

curl "https://api.coincatch.com/api/spot/v1/account/getInfo" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

返回数据

{
    "code": "00000",
    "msg": "success",
    "data": {
        "user_id": "714229403",
        "inviter_id": "682221498",
        "agent_inviter_code":null,
        "channel":null,
        "ips": "172.23.88.91",
        "authorities": [
            "trade",
            "readonly"
        ],
        "parentId":"566624801",
        "trader":false
    }
}

返回值说明

返回字段	字段说明
user_id	uid
inviter_id	邀请人id
agent_inviter_code	渠道邀请码
channel	渠道
ips	apikey 设置IP白名单
authorities	权限
parentId	母账户uid
trader	是否是交易员

获取账户资产

限速规则：10次/1s

HTTP请求 获取账户资产

• GET /api/spot/v1/account/assets

请求参数

参数名	参数类型	是否必须	描述
coin	String	否	币种

请求示例

curl "https://api.coincatch.com/api/spot/v1/account/assets?coin=USDT" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

返回数据

{
  "code":"00000",
  "message":"success",
  "data":[
    {
        "coinId":"10012",
        "coinName":"usdt",
        "available":"0",
        "frozen":"0",
        "lock":"0",
        "uTime":"1622697148"
    }
]
}

返回值说明

返回字段	字段说明
coinId	币种id
coinName	币种名称
available	可用资产
frozen	冻结资产, 通常是下单时冻结
lock	锁仓资产，成为法币商家等的锁仓
uTime	更新时间

获取账单流水

限速规则 10次/1s

HTTP请求

获取账单流水

• POST /api/spot/v1/account/bills

请求参数

参数名	参数类型	是否必须	描述
coinId	Integer	否	币种ID
groupType	String	否	账单大类型 groupType
bizType	String	否	业务类型 bizType
after	String	否	传入 billId， 返回小于该 billId 的数据
before	String	否	传入 billId， 返回大于等于该 billId 的数据
limit	Integer	否	返回结果的数量，默认100，最大 500

请求示例

curl "https://api.coincatch.com/api/spot/v1/account/bills" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d '{ 
    "coinId":"2",
    "groupType":"deposit",
    "bizType":"deposit",
    "before":"987952085712531455",
    "after":"987952085712531457",
    "limit":"100"
}'

返回数据

{
  "code":"00000",
  "message":"success",
  "data":[{
      "cTime":"1622697148",
      "coinId":"22",
      "coinName":"usdt",
      "groupType":"deposit",
      "bizType":"transfer-in", 
      "quantity":"1",
      "balance": "1",
      "fees":"0",
      "billId":"1291"
}]
}

返回值说明

返回字段	字段说明
cTime	创建时间
coinId	币种Id
coinName	币种名称
groupType	流水类型
bizType	流水账单业务类型
quantity	数量
balance	划转之前的资产
fees	手续费
billId	id

• groupType
  • deposit
  • withdraw
  • transaction
  • transfer
  • other
• bizType
  • deposit
  • withdraw
  • buy
  • sell
  • transfer-in
  • transfer-out
  • system-lock
  • user-lock

获取划转记录

限速规则 20次/1s

HTTP请求

• GET /api/spot/v1/account/transferRecords

请求参数

参数名	参数类型	是否必须	描述
coinId	Integer	是	币种ID
fromType	String	是	账单大类型
after	Long	是	传入终止时间，格式为时间戳，单位为秒
before	Long	是	传入起始时间，格式为时间戳，单位为秒
clientOid	String	否	clientOid，精确匹配
limit	Integer	否	返回结果的数量，默认100，最大 500

请求示例

curl "https://api.coincatch.com/api/spot/v1/account/transferRecords?coinId=2&fromType=exchange&after=1659076670&before=1659076670&limit=100" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

返回数据

{
    "code":"00000",
    "data":[
        {
            "coinName":"btc",
            "status":"SUCCESS",
            "toType":"USD_MIX",
            "toSymbol":"",
            "fromType":"CONTRACT",
            "fromSymbol":"BTC/USD",
            "amount":"1000.00000000",
            "tradeTime":"1631070374488",
            "clientOid": "1",
            "transferId": "997381107487641600"
        }
    ],
    "msg":"success",
    "requestTime":1631608142260
}

返回值说明

返回字段	字段说明
coinName	币种名称
status	划转状态
toType	转入账户类型 accountType
toSymbol	转入账户交易对
fromType	转出账户类型 accountType
fromSymbol	转出账户交易对
amount	数量
tradeTime	交易时间 (毫秒时间戳)
clientOid	client order ID
transferId	Transfer ID

• fromType / toType
  • exchange 现货
  • usdt_mix U本位合约账户
  • usdc_mix USDC本位合约账户
  • margin_cross 全仓杠杆账户
  • margin_isolated 逐仓杠杆账户

订单接口

下单

限速规则：10次/1s

交易员限速规则: 1/s (uid)

HTTP请求 下单接口

• POST /api/spot/v1/trade/orders

请求示例

curl -X POST "https://api.coincatch.com/api/spot/v1/trade/orders" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_SPBL","side": "buy","orderType": "limit","force":"normal","price":"23222.5","quantity":"1","clientOrderId":"myorder_16569403333"}'

返回数据

{
    "code":"00000",
    "msg":"success",
    "data":{
        "orderId":"1001",
        "clientOrderId":"hgXjh89AsxleMSw"
    }
}

请求参数

参数名	参数类型	是否必须	描述
symbol	String	是	symbol
side	String	是	交易方向
orderType	String	是	交易类型 limit/market
force	String	是	订单类型
price	String	否	限价价格
quantity	String	是	委托数量, limit时表示base coin数量; market-buy表示quote coin数量
clientOrderId	String	否	自定义订单ID

重复的 clientOrderId

{
    "code": "43118",
    "msg": "clientOrderId duplicate"
}

返回值说明

返回字段	字段说明
orderId	订单ID
clientOrderId	自定义订单ID

 

 

 

 

 

 

 

 

 

 

批量下单

限速规则 5次/1s

交易员限速规则: 1/sec (uid)

HTTP请求

批量下单

• POST /api/spot/v1/trade/batch-orders

请求参数

参数名	参数类型	是否必须	描述
symbol	String	是	symbol
orderList	List	是	下单集合

• orderList参数

参数名	参数类型	是否必须	描述
side	String	是	交易方向
orderType	String	是	交易类型 limit/market
force	String	是	订单类型
price	String	否	限价价格
quantity	String	是	委托数量
clientOrderId	String	否	自定义订单ID

请求示例

curl -X POST "https://api.coincatch.com/api/spot/v1/trade/batch-orders" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_SPBL","orderList":[{"side":"buy","orderType": "limit","force":"normal","price":"23222.5","quantity":"1","clientOrderId":"myorder_16569403333"}] }'

返回参数

{
    "code": "00000",
    "msg": "success",
    "requestTime": 1666336231317,
    "data": {
        "resultList": [
            {
                "orderId": "967249748427186178",
                "clientOrderId": "1"
            }
        ],
        "failure": [
            {
                "orderId": "967249748427186178",
                "clientOrderId": "1",
                "errorMsg": "clientOrderId duplicate"
            }
        ]
    }
}

返回值说明

参数	描述
resultList	成功订单数组
> orderId	订单ID
> clientOrderId	客户端订单ID
failure	失败订单数组
> orderId	订单ID
> clientOrderId	客户端订单ID
> errorMsg	错误信息

撤单

限速规则 10次/1s

HTTP请求

撤单操作

• POST /api/spot/v1/trade/cancel-order

请求参数

参数名	参数类型	是否必须	描述
symbol	String	是	symbol
orderId	String	是	订单id

请求示例

curl -X POST "https://api.coincatch.com/api/spot/v1/trade/cancel-order" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_SPBL","orderId": "34923828882"}'

返回参数

{

  "code":"00000",
   "message":"success",
  "data":"34923828882"
}

撤单V2

限速规则 10次/1s

HTTP请求

撤单操作

• POST /api/spot/v1/trade/cancel-order-v2

请求参数

参数名	参数类型	是否必须	描述
symbol	String	是	symbol
orderId	String	否	订单id，和clientOid必填其中一个
clientOid	String	否	clientOid，和orderId必填其中一个

请求示例

curl -X POST "https://api.coincatch.com/api/spot/v1/trade/cancel-order-v2" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_SPBL","orderId": "34923828882"}'

返回参数

{

  "code":"00000",
   "message":"success",
  "data":{
    "orderId":"34923828881",
    "clientOrderId":"xx001"
  }
}

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

按币对撤单

限速规则 10次/1s

HTTP请求

撤单操作

• POST /api/spot/v1/trade/cancel-symbol-order

请求参数

参数名	参数类型	是否必须	描述
symbol	String	是	symbol

请求示例

curl -X POST "https://api.coincatch.com/api/spot/v1/trade/cancel-symbol-order" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_SPBL"}'

返回参数

{

  "code":"00000",
   "message":"success",
  "data":"BTCUSDT_SPBL"
}

撤单结果应做二次确认

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

批量撤单(单币对)

限速规则 10次/1s

HTTP请求

批量撤单请求

• POST /api/spot/v1/trade/cancel-batch-orders

请求参数

参数名	参数类型	是否必须	描述
symbol	String	是	产品ID
orderIds	String[]	是	订单id数组，最多50个

请求示例

curl -X POST "https://api.coincatch.com/api/spot/v1/trade/cancel-batch-orders" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_SPBL","orderIds": ["34923828882"]}'

返回参数

{

  "code":"00000",
   "message":"success",
    "data":["34923828882"]
}   

 

 

 

 

 

 

 

批量撤单V2(单币对)

限速规则 10次/1s

HTTP请求

批量撤单请求

• POST /api/spot/v1/trade/cancel-batch-orders-v2

请求参数

参数名	参数类型	是否必须	描述
symbol	String	是	产品ID
orderIds	String[]	否	订单id数组，与clientOids必填一个
clientOids	String[]	否	clientOid数组，与orderIds必填一个

请求示例

curl -X POST "https://api.coincatch.com/api/spot/v1/trade/cancel-batch-orders-v2" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_SPBL","orderIds": ["34923828882"]}'

返回参数

{

  "code":"00000",
   "message":"success",
    "data":{
        "resultList":[
            {
                "orderId":"34923828882",
                "clientOrderId":"xxx002"
            }
        ],
        "failure":[
            {
                "clientOrderId":"xxx001",
                "errorMsg":"duplicate clientOrderId",
                "errorCode":"40725"
            }
        ]
    }
}   

 

 

 

 

 

 

 

获取订单详情

限速规则 20次/1s

HTTP请求

根据订单id或者自定义id获取订单

• POST /api/spot/v1/trade/orderInfo

请求参数

参数名	参数类型	是否必须	描述
orderId	String	否	订单id，与clientOrderId二选一
clientOrderId	String	否	自定义id，与orderId二选一 (clientOrderId必须是用户生成的才有效，且只能查询到24小时内的订单)

订单取消或成交后24小时内，可以使用orderId/clientOrderId查询详情；24小时后，需要使用 获取历史委托列表 接口按orderId查询

请求示例

curl -X POST "https://api.coincatch.com/api/spot/v1/trade/orderInfo" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_SPBL","orderId": "34923828882"}'

返回参数

{
    "code": "00000",
    "msg": "success",
    "requestTime": 1684492945476,
    "data": [
        {
            "accountId": "222222222",
            "symbol": "TRXUSDT_SPBL",
            "orderId": "1041901704004947968",
            "clientOrderId": "c5e8a5e1-a07f-4202-8061-b88bd598b264",
            "price": "0",
            "quantity": "10.0000000000000000",
            "orderType": "market",
            "side": "buy",
            "status": "full_fill",
            "fillPrice": "0.0699782527055350",
            "fillQuantity": "142.9015000000000000",
            "fillTotalAmount": "9.9999972790000000",
            "enterPointSource": "API",
            "feeDetail": "{\"BTC\":{\"deduction\":false,\"feeCoinCode\":\"BTC\",\"totalDeductionFee\":0,\"totalFee\":-7.00000E-7},\"newFees\":{\"c\":0,\"d\":0,\"deduction\":false,\"r\":-7E-7,\"t\":-7E-7,\"totalDeductionFee\":0}}",
            "orderSource": "market",
            "cTime": "1684134644509"
        }
    ]
}

返回值说明

返回字段	字段说明
accountId	账户id
symbol	产品ID
orderId	订单id
clientOrderId	自定义id
price	委托价格
quantity	委托数量(orderType=limit时表示base coin; orderType=market时表示quote coin)
orderType	委托类型
side	委托方向
status	订单状态
fillPrice	成交价格
fillQuantity	成交数量
fillTotalAmount	成交总额
enterPointSource	enterPointSource
cTime	创建时间 (时间戳秒)
feeDetail	手续费明细
> deduction	是否抵扣
> feeCoinCode	手续费币种, 如BTC
> totalDeductionFee	抵扣手续费
> totalFee	总手续费
> newFees	Object
>> t	总手续费, 'buy'时按左币计算, 'sell'时按右币计算
>> d	抵扣手续费: BTC 数量
>> r	实付手续费, 'buy'时按左币计算, 'sell'时按右币计算
>> c	抵扣券抵扣的金额: 'buy'时按左币计算, 'sell'时按右币计算
orderSource	orderSource

获取未成交列表

限速规则 20次/1s

HTTP请求

获取未成交和部分成交未撤单的订单

• POST /api/spot/v1/trade/open-orders

请求参数

参数名	参数类型	是否必须	描述
symbol	String	否	产品ID,如果查全部传空

请求示例

curl -X POST "https://api.coincatch.com/api/spot/v1/trade/open-orders" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_SPBL"}'

返回参数

{
  "code":"00000",
  "message":"success",
"data":[{
  "accountId":"10012",
  "symbol":"btcusdt_spbl",
  "orderId":"2222222",
  "clientOrderId":"xxxxxxx",
  "price":"34829.12",
  "quantity":"1",  
  "orderType":"limit",
  "side":"buy",
  "status":"new",
  "fillPrice":"0",
  "fillQuantity":"0",
  "fillTotalAmount":"0",
  "enterPointSource": "WEB",
  "cTime":"1622697148"
}]
}

返回值说明

返回字段	字段说明
accountId	账户id
symbol	产品ID
orderId	订单id
clientOrderId	自定义id
price	委托价格
quantity	委托数量(orderType=limit时表示base coin; orderType=market时表示quote coin)
orderType	委托类型
side	委托方向
status	订单状态
fillPrice	累计成交价格
fillQuantity	累计成交数量
fillTotalAmount	成交总额
enterPointSource	enterPointSource
cTime	创建时间 (时间戳秒)

获取历史委托列表

限速规则 20次/1s

HTTP请求

获取全部成交和已撤销的订单

• POST /api/spot/v1/trade/history

请求参数

参数名	参数类型	是否必须	描述
symbol	String	是	产品ID
after	String	否	orderId， 返回 小于该orderId 数据
before	String	否	orderId， 返回 大于orderId 数据
limit	Integer	否	返回结果的数量，默认100，最大 500

请求示例

curl -X POST "https://api.coincatch.com/api/spot/v1/trade/history" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_SPBL","after":"1659076670000","before":"1659076670000","limit":"100"}'

返回参数

{
  "code": "00000",
  "msg": "success",
  "requestTime": 1684493060724,
  "data": [
    {
      "accountId": "2222222222",
      "symbol": "TRXUSDT_SPBL",
      "orderId": "1041901704004947968",
      "clientOrderId": "c5e8a5e1-a07f-4202-8061-b88bd598b264",
      "price": "0",
      "quantity": "10.0000000000000000",
      "orderType": "market",
      "side": "buy",
      "status": "full_fill",
      "fillPrice": "0.0699782527055350",
      "fillQuantity": "142.9015000000000000",
      "fillTotalAmount": "9.9999972790000000",
      "enterPointSource": "API",
      "feeDetail": "{\"BTC\":{\"deduction\":false,\"feeCoinCode\":\"BTC\",\"totalDeductionFee\":0,\"totalFee\":-7.00000E-7},\"newFees\":{\"c\":0,\"d\":0,\"deduction\":false,\"r\":-7E-7,\"t\":-7E-7,\"totalDeductionFee\":0}}",
      "orderSource": "market",
      "cTime": "1684134644509"
    }
  ]
}

返回值说明

返回字段	字段说明
accountId	账户id
symbol	产品ID
orderId	订单id
clientOrderId	自定义id
price	委托价格
quantity	委托数量(orderType=limit时表示base coin; orderType=market时表示quote coin)
orderType	委托类型
side	委托方向
status	订单状态
fillPrice	成交价格
fillQuantity	成交数量
fillTotalAmount	成交总额
enterPointSource	enterPointSource
cTime	创建时间 (时间戳秒)
feeDetail	手续费明细
> deduction	是否抵扣
> feeCoinCode	手续费币种, 如BTC
> totalDeductionFee	抵扣手续费
> totalFee	总手续费
> newFees	Object
>> t	总手续费, 'buy'时按左币计算, 'sell'时按右币计算
>> d	抵扣手续费: BTC 数量
>> r	实付手续费, 'buy'时按左币计算, 'sell'时按右币计算
>> c	抵扣券抵扣的金额: 'buy'时按左币计算, 'sell'时按右币计算
orderSource	orderSource

获取成交明细

限速规则 20次/1s

HTTP请求

获取成交的历史明细

• POST /api/spot/v1/trade/fills

请求参数

参数名	参数类型	是否必须	描述
symbol	String	是	产品Id
orderId	String	否	订单ID
after	String	否	Max orderId， 返回小于 orderId 的数据
before	String	否	Min orderId 返回大于等于 orderId 的数据
limit	Integer	否	返回结果的数量，默认100，最大 500

请求示例

curl -X POST "https://api.coincatch.com/api/spot/v1/trade/fills" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_SPBL","orderId":"34923828882","after":"349234552212","before":"34923775522","limit":"100"}'

返回参数

{
  "code":"00000",
  "message":"success",
  "data":[{
  "accountId":"1001",
  "symbol":"btcusdt_spbl",
  "orderId":"100021",
  "fillId":"102211",
  "orderType":"limit",
  "side":"buy",
  "fillPrice":"38293.12",
  "fillQuantity":"1",
  "fillTotalAmount":"38293.12",
  "cTime":"1622697148",
  "feeCcy":"btc",
  "fees":"0.0001"
}]
}

返回值说明

返回字段	字段说明
accountId	账户id
symbol	产品ID
orderId	订单id
fillId	成交id
orderType	委托类型
side	委托方向
fillPrice	成交价格
fillQuantity	成交数量
fillTotalAmount	成交总额
cTime	创建时间 (时间戳秒)
feeCcy	手续费币种
fees	手续费

下计划委托

限速规则 20次/1s

HTTP请求

下计划委托

• POST /api/spot/v1/plan/placePlan

请求参数

参数名	参数类型	是否必须	描述
symbol	String	是	产品Id
side	String	是	方向 (buy/sell)
triggerPrice	BigDecimal	是	触发价格
executePrice	BigDecimal	否	执行价格，orderType=limit时不能为空
size	BigDecimal	是	购买数量，orderType=limit时为base coin数量；orderType=market时为quote coin数量
triggerType	String	是	触发类型 (fill_price/market_price)
orderType	String	是	订单类型 (limit/market)
clientOid	String	否	客户自定义order ID, 幂等控制
timeInForceValue	String	否	订单有效期
placeType	String	否	下单类型（按照数量下单类型：amount ，按照金额下单类型：total）

请求 shell curl -X POST "https://api.coincatch.com/api/spot/v1/plan/placePlan" \ -H "ACCESS-KEY:you apiKey" \ -H "ACCESS-SIGN:*******" \ -H "ACCESS-PASSPHRASE:*****" \ -H "ACCESS-TIMESTAMP:1659076670000" \ -H "locale:en-US" \ -H "Content-Type: application/json" \ -d \'{"symbol": "TRXUSDT_SPBL", "side": "buy", "triggerPrice": 0.041572, "executePrice": "0.041572", "size": 151, "triggerType": "market_price", "orderType": "limit","clientOid": "12345", "timeInForceValue": "normal"}'

返回参数

{
  "code": "00000",
  "msg": "success",
  "requestTime": 1668134576535,
  "data": {
    "orderId": "974792555020390400",
    "clientOrderId": "974792554995224576"
  }
}

返回值说明

返回字段	字段说明
orderId	订单ID
clientOrderId	自定义ID

 

 

 

 

 

 

 

 

 

 

修改计划委托

限速规则 20次/1s

HTTP请求

• POST /api/spot/v1/plan/modifyPlan

请求参数

参数名	参数类型	是否必须	描述
orderId	String	否	订单ID, 'orderId' 或 'clientOid' 必需提供一个
clientOid	String	否	clientOid, 'orderId' 或 'clientOid' 必需提供一个
triggerPrice	BigDecimal	是	触发价格
executePrice	BigDecimal	否	执行价格
size	String	否	购买数量
orderType	String	是	订单类型 （limit/market）

请求示例

curl -X POST "https://api.coincatch.com/api/spot/v1/plan/modifyPlan" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"orderId": "974792060738441216", "triggerPrice": 0.041222, "executePrice":"0.041272", "size": 156, "orderType":"limit"}'

返回参数

{
  "code": "00000",
  "msg": "success",
  "requestTime": 1668136575920,
  "data": {
    "orderId": "974792060738441216",
    "clientOrderId": "974792554995224576"
  }
}

返回值说明

返回字段	字段说明
orderId	订单ID
clientOrderId	自定义ID

 

 

 

 

 

 

 

 

 

 

撤销计划委托

限速规则 20次/1s

HTTP请求

撤销计划委托

• POST /api/spot/v1/plan/cancelPlan

请求参数

参数名	参数类型	是否必须	描述
orderId	String	否	订单ID, 'orderId' 或 'clientOid' 必需提供一个
clientOid	String	否	clientOid, 'orderId' 或 'clientOid' 必需提供一个

请求示例

curl -X POST "https://api.coincatch.com/api/spot/v1/plan/cancelPlan" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"orderId": "974792060738441216"}'

返回参数

{
  "code": "00000",
  "msg": "success",
  "requestTime": 1668134497496,
  "data": "974792060738441216"
}

返回值说明

返回字段	字段说明
data	orderId或clientOid，原值返回

 

 

 

 

 

 

 

 

 

 

获取当前计划委托

限速规则 20次/1s

HTTP请求

获取当前计划委托

• POST /api/spot/v1/plan/currentPlan

请求参数

参数名	参数类型	是否必须	描述
symbol	String	是	产品Id
pageSize	String	是	分页
lastEndId	String	否	最后ID （分页需要）

请求示例

curl -X POST "https://api.coincatch.com/api/spot/v1/plan/currentPlan" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{ "symbol": "TRXUSDT_SPBL", "pageSize":"20" }'

返回参数

{
  "code": "00000",
  "msg": "success",
  "requestTime": 1668134581005,
  "data": {
    "nextFlag": false,
    "endId": 974792555020390400,
    "orderList": [
      {
        "orderId": "974792555020390400",
        "clientOid":"xxx001",
        "symbol": "TRXUSDT_SPBL",
        "size": "151",
        "executePrice": "0.041572",
        "triggerPrice": "0.041572",
        "status": "not_trigger",
        "orderType": "limit",
        "side": "buy",
        "triggerType": "fill_price",
        "enterPointSource": "API",
        "cTime": "1668134576563"
      }
    ]
  }
}

返回值说明

返回字段	字段说明
orderId	订单ID
clientOid	Client Order ID
symbol	产品ID
size	购买数量，orderType=limit时为base coin数量；orderType=market时为quote coin数量
executePrice	执行价格
triggerPrice	触发价格
status	状态
orderType	订单类型
side	购买方向
triggerType	触发类型
enterPointSource	enterPointSource
cTime	创建时间
placeType	下单类型

 

 

 

 

 

 

 

 

 

 

 

 

 

 

获取历史计划委托

限速规则 20次/1s

HTTP请求

获取历史改计划委托

• POST /api/spot/v1/plan/historyPlan

请求参数

参数名	参数类型	是否必须	描述
symbol	String	是	产品Id
pageSize	String	是	分页
startTime	String	是	开始时间 （托管子账户访问时，StartTime 时间不能早于 绑定开始的时间）
endTime	String	是	结束时间
lastEndId	String	否	最后ID （分页需要）

请求示例

curl -X POST "https://api.coincatch.com/api/spot/v1/plan/historyPlan" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{ "symbol": "TRXUSDT_SPBL", "pageSize":"20", "startTime":"1667889483000", "endTime":"1668134732000" }'

返回参数

{
  "code": "00000",
  "msg": "success",
  "requestTime": 1668134626684,
  "data": {
    "nextFlag": false,
    "endId": 974792060738441216,
    "orderList": [
      {
        "orderId": "974792060738441216",
        "clientOid":"xxx001",
        "symbol": "TRXUSDT_SPBL",
        "size": "156",
        "executePrice": "0.041272",
        "triggerPrice": "0.041222",
        "status": "cancel",
        "orderType": "limit",
        "side": "buy",
        "triggerType": "fill_price",
        "enterPointSource": "API",
        "cTime": "1668134458717"
      }
    ]
  }
}

返回值说明

返回字段	字段说明
orderId	订单ID
clientOid	Client Order ID
symbol	产品ID
size	购买数量，orderType=limit时为base coin数量；orderType=market时为quote coin数量
executePrice	执行价格
triggerPrice	触发价格
status	状态
orderType	订单类型
side	购买方向
triggerType	触发类型
enterPointSource	enterPointSource
cTime	创建时间
placeType	下单类型

 

 

 

 

批量撤销计划委托单

限速规则 10次/1s

HTTP请求

获取历史改计划委托

• POST /api/spot/v1/plan/batchCancelPlan

请求参数

参数名	参数类型	是否必须	描述
symbols	List	否	币对集合：["BTCUSDT_SPBL", "ETHUSDT_SPNL"], 请注意，没传币对的时候会撤销所有现货计划委托单

请求示例

curl -X POST "https://api.coincatch.com/api/spot/v1/plan/batchCancelPlan" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{ "symbols": ["BTCUSDT_SPBL", "ETHUSDT_SPNL"] }'

返回参数

{
  "code": "00000",
  "msg": "success",
  "requestTime": 1683876261117,
  "data": [
    {
      "orderId": "10401817882538259200",
      "clientOid": "10408117882913093376",
      "result": true
    },
    {
      "orderId": "10401817887238259200",
      "clientOid": "10401817882213193376",
      "result": true
    }
  ]
}

返回值说明

返回字段	字段说明
orderId	委托订单ID
clientOid	委托订单 Client Order ID
result	撤销成功

WebSocketAPI

概述

WebSocket是HTML5一种新的协议(Protocol)。它实现了客户端与服务器全双工通信， 使得数据可以快速地双向传播。通过一次简单的握手就 可以建立客户端和服务器连接， 服务器根据业务规则可以主动推送信息给客户端。其优点如下：

• 客户端和服务器进行数据传输时，请求头信息比较小，大概2个字节。
• 客户端和服务器皆可以主动地发送数据给对方。
• 不需要多次创建TCP请求和销毁，节约宽带和服务器的资源。

强烈建议开发者使用WebSocket API获取市场行情和买卖深度等信息。 ​

域名	WebSocket API	建议使用
公共频道域名	wss://ws.coincatch.com/public/v1/stream	国际
私有频道域名	wss://ws.coincatch.com/private/v1/stream	国际

连接说明：

连接上ws后30s内订阅或订阅后30s内用户未发送ping指令，系统会自动断开连接

连接

连接说明：

连接限制：100个/IP

订阅限制：240次/小时

如果出现网络问题，系统会自动断开连接

如果连接成功后30s未订阅或订阅后30s内服务器未向用户推送数据，系统会自动断开连接

为了保持连接有效且稳定，建议您进行以下操作：

1. 每次接收到消息后，用户设置一个定时器，定时30秒。
2. 如果定时器被触发（30秒内没有收到新消息），发送字符串 'ping'。
3. 期待一个文字字符串'pong'作为回应。如果在30秒内未收到，请发出错误或重新连接。
4. Websocket服务器每秒最多接受10个消息。消息包括:
5. PING帧
6. JSON格式的消息，比如订阅，断开订阅。
7. 如果用户发送的消息超过限制，连接会被断开连接。反复被断开连接的IP有可能被服务器屏蔽；
8. 单个连接最多可以订阅 1000 个Streams；
9. 单个IP最多可以创建100个连接。

登录

api_key:用于调用API的用户身份唯一标示，需要用户申请

passphrase:API Key 的密码,如果没有口令的话传入空字符串("")即可

timestamp: 时间戳 是Unix Epoch时间，单位是秒， 时间戳30秒后会过期

sign:为签名字符串，签名规则参照如下:

Message即(待签名字符串)为： timestamp+method+requestPath

其中timestamp示例:const timestamp = '' + Date.now() / 1000

method一律默认为'GET'

requestPath 一律默认为'/user/verify'

请求在时间戳之后30秒会失效，如果您的服务器时间和API服务器时间有偏差，推荐使用 REST API查询API服务器的时间，然后设置时间戳

签名方式说明参考API概述里的验证部分

生成最终签名的步骤

第1步，将待签名字符串使用私钥secretkey进行hmac sha256加密

Signature = hmac_sha256(secretkey, Message)

第2步，对于Signature进行base64编码

Signature = base64.encode(Signature)

如果登录失败会自动断开链接

请求格式说明：

{
    "op": "login",
    "args": [{
        "apiKey": "<api_key>",
        "passphrase": "<passphrase>",
        "timestamp": "<timestamp>",
        "sign": "<sign>"
    }]
}

请求示例：

{
    "op": "login",
    "args": [{
        "apiKey": "bg_573af5eca856acd91c230da294ce2105",
        "passphrase": "123456",
        "timestamp": "1538054050",
        "sign": "8RCOqCJAhhEh4PWcZB/96QojLDqMAg4qNynIixFzS3E="
    }]
} 

成功返回示例：

{
    "event": "login",
    "code": "0",
    "msg": ""
} 

失败返回示例：

{
    "event": "error",
    "code": "30005",
    "msg": "error"
} 

订阅

订阅说明

请求格式说明

{
    "op": "subscribe",
    "args": ["<SubscriptionTopic> "]
}

WebSocket 频道分成两类： 公共频道 和 私有频道

公共频道无需登录，包括行情频道，K线频道，交易数据频道，深度数据频道等。

• instId 来源 /products 的 symbolName

私有频道需登录，包括用户账户频道，用户交易频道等。

• 用户账户频道 instId 为 default 获取全部币种资产

用户可以选择订阅一个或者多个频道，多个频道总长度不能超过4096个字节。

请求示例

{
    "op": "subscribe",
    "args": [{
        "instType": "SP",
        "channel": "ticker",
        "instId": "BTCUSDT"
    }, {
        "instType": "SP",
        "channel": "candle5m",
        "instId": "BTCUSDT"
    }]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作，subscribe
args	Array	是	请求订阅的频道列表
> instType	String	否	产品类型SP：币币公共频道SPBL：币币私有频道
> channel	String	是	频道名
> instId	String	否	产品ID

返回示例

{
    "event": "subscribe",
    "args": {
        "instType": "SP",
        "channel": "ticker",
        "instId": "BTCUSDT"
    }
} 

返回参数

参数	类型	是否必须	描述
event	String	是	事件，subscribe error
arg	Object	否	订阅的频道
> instType	String	否	产品类型SP：币币公共频道SPBL：币币私有频道
> channel	String	是	频道名
> instId	String	否	产品ID
code	String	否	错误码
msg	String	否	错误消息

取消订阅

可以取消一个或者多个频道

请求格式说明

{
    "op": "unsubscribe",
    "args": ["< SubscriptionTopic > "]
}

请求示例

{
    "op": "unsubscribe",
    "args": [{
        "instType": "SP",
        "channel": "ticker",
        "instId": "BTCUSDT"
    }, {
        "instType": "SP",
        "channel": "candle1m",
        "instId": "BTCUSDT"
    }]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作，unsubscribe
args	Array	是	取消订阅的频道列表
> instType	String	是	产品类型SP：币币公共频道SPBL：币币私有频道
> channel	String	是	频道名
> instId	String	是	产品ID或者产品名称

返回示例

{
    "event": "unsubscribe",
    "args": {
        "instType": "SP",
        "channel": "ticker",
        "instId": "BTCUSDT"
    }
} 

返回参数

参数	类型	是否必须	描述
event	String	是	事件，unsubscribe error
arg	Object	是	取消订阅的频道
> instType	String	是	产品类型SP：币币公共频道SPBL：币币私有频道
> channel	String	是	频道名
> instId	String	是	产品ID或者产品名称
code	String	否	错误码
msg	String	否	错误消息

Checksum机制

此机制可以帮助用户校验深度数据的准确性。

深度合并

用户订阅增量推送（如：books400档）深度频道成功后，首先获取初始全量深度数据，当获取到增量推送数据后，更新本地全量深度数据。

1. 如果有相同价格，则比较数量；数量为0删除此深度，数量有变化则替换此数据。
2. 如果没有相同价格，则按照价格优劣排序（bids为价格降序，asks为价格升序），将深度信息插入到全量数据中

计算校验和

先用深度合并后前25档bids和asks组成一个字符串（其中ask和bid中的价格和数量以冒号连接），再计算其crc32值（32位有符号整型）。

1.bid和ask超过25档
合并后全量深度数据（在此仅展示2档数据，实际应截取前25档数据）：
"bids": [
    [ 3366.1, 7],   //bid1
    [ 3366  , 6]
]
"asks": [
    [ 3366.8, 9 ],  //ask1
    [ 3368, 8]
]
校验字符串：
"3366.1:7:3366.8:9:3366:6:3368:8"

2.bid或ask不足25档  
合并后全量深度数据：
"bids": [
    [ 3366.1, 7]
]
"asks": [
    [ 3366.8,9],
    [ 3368,8],
    [ 3372,8]
]
校验字符串：
"3366.1:7:3366.8:9:3368:8:3372:8"

1. 当bid和ask深度数据超过25档时，截取各自25档数据，要校验的字符串按照bid、ask深度数据交替方式连接。如：bid1[价格:数量]:ask1[价格:数量]:bid2[价格:数量]:ask2[价格:数量]...
2. bid或ask深度数据不足25档时，直接忽略缺失的深度。如：bid1[价格:数量]:ask1[价格:数量]:ask2[价格:数量]:ask3[价格:数量]...
3. 如果返回的价格为0.5000, 请注意使用原始值计算checksum，不要使用trim掉0后的0.5

公共频道

行情频道

获取产品的最新成交价、买一价、卖一价和24小时交易量等信息，200ms推送一次数据

请求示例

{
    "op": "subscribe",
    "args": [{
        "instType": "SP",
        "channel": "ticker",
        "instId": "BTCUSDT"
    }]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作，subscribe unsubscribe
args	Array	是	请求订阅的频道列表
> instType	String	是	产品类型，SP
> channel	String	是	频道名，ticker
> instId	String	是	产品名称 BTCUSDT

成功返回示例

{
    "op": "subscribe",
    "args": [{
        "instType": "SP",
        "channel": "ticker",
        "instId": "BTCUSDT"
    }]
}

失败返回示例

{
  "event":"error",
  "arg":
    {
      "instType":"SP",
      "channel":"ticker",
      "instId":"BTC-USDT"
    },
  "code":30001,
  "msg":"instType:SP,channel:ticker,instId:BTC-USDT doesn't exist",
  "op":"subscribe"
}

返回参数

参数	类型	是否必须	描述
event	String	是	事件，subscribe unsubscribe error
arg	Object	否	订阅的频道
> instType	String	是	产品类型
> channel	String	是	频道名
> instId	String	是	产品名称
code	String	否	错误码
msg	String	否	错误消息

推送示例

{
    "action": "snapshot",
    "arg": {
        "instType": "sp",
        "channel": "ticker",
        "instId": "BTCUSDT"
    },
    "data": [
        {
            "instId": "BTCUSDT",
            "last": "20193.17",
            "open24h": "19112.64",
            "high24h": "20374.29",
            "low24h": "18973.16",
            "bestBid": "20192.420000",
            "bestAsk": "20196.440000",
            "baseVolume": "13177.3815",
            "quoteVolume": "261300702.3745",
            "ts": 1664292040025,
            "labeId": 0,
            "openUtc": "19226.5300000000000000",
            "chgUTC": "0.05028",
            "bidSz": "0.06",
            "askSz": "0.0119"
        }
    ]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> instType	String	产品类型
> channel	String	频道名
> instId	String	产品名称
action	String	推送数据动作，增量推送数据还是全量推送数据snapshot：全量update：增量
data	Array	订阅的数据
> instId	String	产品名称
> last	String	最新成交价
> bestAsk	String	卖一价
> bestBid	String	买一价
> open24h	String	24小时开盘价
> high24h	String	24小时最高价
> low24h	String	24小时最低价
> baseVol	String	24小时成交量，以左币为单位
> quoteVol	String	24小时成交量，以右币为单位
> ts	String	数据产生时间，Unix时间戳的毫秒数格式，如 1597026383085
>labeId	Long	Label ID
>openUtc	String	UTC 时间开盘价
>chgUTC	String	自openUtc以来的涨跌: (last - openUtc) / openUtc, 精度 e-5
>bidSz	String	买一量
>askSz	String	卖一量

K线频道

获取产品的K线数据

请求示例

{
    "op": "subscribe",
    "args": [{
        "instType": "sp",
        "channel": "candle1m",
        "instId": "BTCUSDT"
    }]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作，subscribe unsubscribe
args	Array	是	请求订阅的频道列表
>instType	String	是	产品类型 SP
>channel	String	是	频道名，candle1W candle1D candle12H candle4H  candle1H candle30m   candle15m  candle5m  candle1m
> instId	String	是	产品名称 例如:BTCUSDT

成功返回示例

{
    "event": "subscribe",
    "arg": {
        "instType": "sp",
        "channel": "candle1D",
        "instId": "BTCUSDT"
    }
} 

失败返回示例

{
  "event":"error",
  "arg":
    {
      "instType":"sp",
      "channel":"candle1D",
      "instId":"BTC-USDT"
    },
  "code":30001,
  "msg":"instType:sp,channel:candle1D,instId:BTC-USDT doesn't exist",
  "op":"subscribe"
}

返回参数

参数	类型	是否必须	描述
event	String	是	事件，subscribe unsubscribe error
arg	Object	否	订阅的频道
> instType	String	是	产品类型
> channel	String	是	频道名
> instId	String	是	产品名称
code	String	否	错误码
msg	String	否	错误消息

推送示例

{
    "arg": {
        "instType": "sp",
        "channel": "candle1D",
        "instId": "BTCUSDT"
    },
    "data": [
        ["1597026383085", "8533.02", "8553.74", "8527.17", "8548.26", "45247"]
    ]
} 

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> instType	String	产品类型
> channel	String	频道名
> instId	String	产品名称
data	Array	订阅的数据
> ts	String	开始时间，Unix时间戳的毫秒数格式，如 1597026383085
> o	String	开盘价格
> h	String	最高价格
> l	String	最低价格
> c	String	收盘价格
> v	String	数值为左币交易量

深度频道

获取深度数据

books 首次推全量快照数据，以后增量推送，以后增量推送，即有深度有变化推送一次变化的数据

books5首次推5档快照数据，以后全量推送，有深度变化推送一次5档数据，即每次都推送5档数据

books15 首次推15档快照数据，以后全量推送，有深度变化推送一次15档数据，即每次都推送15档数据

请求示例

{
    "op": "subscribe",
    "args": [{
        "instType": "sp",
        "channel": "books5",
        "instId": "BTCUSDT"
    }]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作，subscribe unsubscribe
args	Array	是	请求订阅的频道列表
> instType	String	是	产品类型 SP
> channel	String	是	频道名，books books5 books15
> instId	String	是	产品名称 例如:BTCUSDT

返回示例

{
    "event": "subscribe",
    "arg": {
        "instType": "sp",
        "channel": "books5",
        "instId": "BTCUSDT"
    }
}

失败示例

{
  "event":"error",
  "arg":
    {
      "instType":"sp",
      "channel":"books5",
      "instId":"BTC-USDT"
    },
  "code":30001,
  "msg":"instType:sp,channel:books5,instId:BTC-USDT doesn't exist",
  "op":"subscribe"
}

返回参数

参数	类型	是否必须	描述
event	String	是	事件，subscribe unsubscribe error
arg	Object	否	订阅的频道
> instType	String	是	产品类型 SP
> channel	String	是	频道名
> instId	String	是	产品名称
msg	String	否	错误消息
code	String	否	错误码

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> instType	String	产品类型
> channel	String	频道名
> instId	String	产品名称
action	String	推送数据动作，增量推送数据还是全量推送数据snapshot：全量 update：增量
data	Array	订阅的数据
> asks	Array	卖方深度
> bids	Array	买方深度
> ts	String	数据更新时间戳，Unix时间戳的毫秒数格式，如 1597026383085
> checksum	Integer	检验和

asks和bids值数组举例说明： ["411.8", "10"] 411.8为深度价格，10为此价格的基础币量

交易频道

获取最近的成交数据，有成交数据就推送

请求示例

{
    "op": "subscribe",
    "args": [{
        "instType": "sp",
        "channel": "trade",
        "instId": "BTCUSDT"
    }]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作，subscribe unsubscribe
args	Array	是	请求订阅的频道列表
> instType	String	是	产品类型 SP
> channel	String	是	频道名，trade
> instId	String	是	产品名称

成功返回示例

{
    "event": "subscribe",
    "arg": [{
        "instType": "sp",
        "channel": "trade",
        "instId": "BTCUSDT"
    }]
}

失败返回示例

{
  "event":"error",
  "arg":
    {
      "instType":"spbl",
      "channel":"trade",
      "instId":"BTC-USDT"
    },
  "code":30001,
  "msg":"instType:spbl,channel:trade,instId:BTC-USDT doesn't exist",
  "op":"subscribe"
}

返回参数

参数	类型	是否必须	描述
event	String	是	事件，subscribe unsubscribe error
arg	Object	否	订阅的频道
> instType	String	是	产品类型
> channel	String	是	频道名
> instId	String	是	产品名称
code	String	否	错误码
msg	String	否	错误消息

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> instType	String	产品类型
> channel	String	频道名
> instId	String	产品名称
data	Array	订阅的数据
> ts	String	成交时间，Unix时间戳的毫秒数格式，如 1597026383085
> px	String	成交价格
> sz	String	成交数量
> side	String	成交方向，buy 买 sell卖

私有频道

账户频道

获取账户信息，首次订阅按照订阅维度推送数据，此外，当下单、撤单等事件触发时，推送数据

请求示例

{
    "op": "subscribe",
    "args": [{
        "instType": "spbl",
        "channel": "account",
        "instId": "default"
    }]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作，subscribe unsubscribe
args	Array	是	请求订阅的频道列表
> instType	String	是	产品类型,spbl
> channel	String	是	频道名，account
> instId	String	是	币种, 全部传 default

成功返回示例

{
    "event": "subscribe",
    "arg": {
        "instType": "spbl",
        "channel": "account",
        "instId": "default"
    }
} 

失败返回示例

{
  "event":"error",
  "arg":
    {
      "instType":"spbl",
      "channel":"account",
      "instId":"BTC-USDT"
    },
  "code":30003,
  "msg":"instType:spbl,channel:account,instId:BTC-USDT doesn't exist",
  "op":"subscribe"
}

返回参数

参数	类型	是否必须	描述
event	String	是	操作，subscribe unsubscribe error
arg	Object	否	订阅的频道
> instType	String	是	产品类型
> channel	String	是	频道名
> instId	String	否	币种
code	String	否	错误码
msg	String	否	错误消息

推送示例

{
    "action": "snapshot",
    "arg": {
        "instType": "spbl",
        "channel": "account",
        "instId": "default"
    },
    "data": [{
        "coinId": "2",
        "coinName": "USDT",
        "available": "1000.0000"
    }, {
        "coinId": "1",
        "coinName": "BTC",
        "available": "1.35000"
    }]
}

推送数据参数

参数名	类型	描述
arg	Object	请求订阅的频道
> instType	String	产品类型
> channel	String	频道名
> instId	String	币种
data	Array	订阅的数据
> coinId	String	币种id
> coinName	String	币种名称
> available	String	币种余额

首次推送:全量推送。

增量推送：推送交易变化

订单频道

获取订单信息，首次订阅不推送，只有当下单、撤单、成交等事件触发时，推送数据

请求示例

{
    "op": "subscribe",
    "args": [{
        "channel": "orders",
        "instType": "spbl",
        "instId": "BTCUSDT_SPBL"
    }]
}

请求参数

参数	类型	是否必须	描述
> instId	String	是	产品ID
op	String	是	操作，subscribe unsubscribe
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名, orders
> instType	String	是	产品类型,spbl
> instId	String	是	BTCUSDT_SPBL

成功返回示例

{
    "event": "subscribe",
    "arg": {
        "channel": "orders",
        "instType": "spbl",
        "instId": "BTCUSDT_SPBL"
    }
}

失败返回示例

{
  "event":"error",
  "arg":
    {
      "instType":"spbl",
      "channel":"account",
      "instId":"BTC-USDT"
    },
  "code":30003,
  "msg":"instType:spbl,channel:orders,instId:BTC-USDT doesn't exist",
  "op":"subscribe"
}

返回参数

参数	类型	是否必须	描述
event	String	是	事件，subscribe unsubscribe errror
arg	Object	否	订阅的频道
> channel	String	是	频道名
> instType	String	是	产品类型
> instId	String	否	产品ID
code	String	否	错误码
msg	String	否	错误消息

 

推送数据示例

{
  "data":[
    {
      "notional":"6.290480",
      "side":"buy",
      "sz":"0.0040",
      "px":"1572.62",
      "orderFee":[

      ],
      "eps":"WEB",
      "cTime":1678789919603,
      "ordId":"10194123402951243161",
      "instId":"ETHUSDT_SPBL",
      "clOrdId":"b712d4e8-bec1-4124-ae83-e7aa44cfcdd2",
      "accFillSz":"0.0000",
      "avgPx":"0.00",
      "force":"normal",
      "uTime":1678789919603,
      "ordType":"limit",
      "status":"new"
    }
  ],
  "arg":{
    "instType":"spbl",
    "instId":"default",
    "channel":"orders"
  },
  "action":"snapshot"
}

 

推送数据参数

arg	Object	订阅成功的频道
> channel	String	频道名
> instType	String	产品类型
> instId	String	产品ID
data	Array	订阅的数据
> instId	String	产品ID
> ordId	String	订单ID
> clOrdId	String	用户设置的订单ID来识别您的订单
> px	String	委托价格
> sz	String	委托数量（交易货币数量）
> notional	String	买入金额，市价买入时返回
> ordType	String	订单类型 market：市价单 limit：限价单
> force	String	订单有效期normal：普通委托post_only： 只做maker单fok：全部成交或立即取消单ioc：立即成交并取消剩余单
> side	String	订单方向，buy sell
> fillPx	String	最新成交价格
> tradeId	String	最新成交ID
> fillSz	String	最新成交数量
> fillTime	String	最新成交时间
> fillFee	String	最新一笔成交的手续费, 负数
> fillFeeCcy	String	最新一笔成交的手续费币种
> execType	String	最新一笔成交的流动性方向 T：taker M: maker
> accFillSz	String	累计已成交数量
> avgPx	String	累计成交均价，如果成交数量为0，该字段也为0
> status	String	订单状态 init 插入DB, new:orderbook未成交 partial-fill 部分成交 full-fill：完全成交 cancelled：已撤单
> eps	String	enterPointSource
> cTime	String	订单创建时间，Unix时间戳的毫秒数格式，如 1630410492847
> uTime	String	订单更新时间，Unix时间戳的毫秒数格式，如 1630410493060
>orderFee	Array	手续费list
>> feeCcy	String	交易手续费币种
>> fee	String	订单交易手续费，平台向用户收取的交易手续费

RestAPI错误

公共错误码

错误提示	错误码	http状态码
请求头"ACCESS_KEY"不能为空	40001	400
请求头"ACCESS_SIGN"不能为空	40002	400
请求头"ACCESS_TIMESTAMP"不能为空	40003	400
无效的ACCESS_TIMESTAMP	40005	400
无效的ACCESS_KEY	40006	400
无效的Content_Type，请使用“application/json”格式	40007	400
请求时间戳过期	40008	400
api 校验失败	40009	400
请求太频繁	429	429
请求头"ACCESS_PASSPHRASE"不能为空	40011	400
apikey/passphrase不正确	40012	400
用户被冻结	40013	400
权限不正确	40014	400
系统错误	40015	400
用户必须绑定手机或者谷歌	40016	400
参数校验失败	40017	400
非法的ip请求	40018	400