欢迎使用 CipherBC API
接入准备
1 申请APP_ID
联系客服人员申请APP_ID,需要提供相关资质信息。 例如:公司名称,域名,IP, 第一负责人及其他商务需要信息。
2 提供需要支持的主链与合约币种清单
合约币需要合约地址、所属主链、精度、名称等基本信息给到业务对接人。
3 接口测试环境调试
接口测试环境对接,联调,演练。 接口采用 RSA2048位 双向签名验签形式确保通信可信性。 商户需要提前将公钥给到平台,用于平台对商户请求参数验签。 商户需要提前获取平台公钥,用于对平台响应结果验签。
支持公链
签名规则
新接入商户请使用 V2 签名方式,平台不再支持新商户使用 V1,存量商户可继续使用 V1。
本文档按 v2 签名编写。v2 的身份和签名放在 HTTP Header 中,请求体只包含业务字段,算法固定为 RSA-SHA256(RSA PKCS#1 v1.5 + SHA-256),签名值为标准 Base64。
- 请求:商户用商户私钥签名,平台用商户公钥验签。
- 响应、结果通知:平台用平台私钥签名,商户用平台公钥验签。
- 提现订单二次复核、兑换订单二次复核 两个风控接口共用独立风控密钥对,详见风控回调。
- 摘要按实际发送的原始字节计算。签名之后不得再重新序列化 body,否则验签失败。
- 时间戳允许的偏差为 300 秒,请保持服务器时钟同步。
请求签名
请求示例:
POST <base_path>/v2/balance HTTP/1.1
Host: api.xxxx.com
Content-Type: application/json
X-Cbc-App-Id: hxgmau9imt86qky9
X-Cbc-Key-Version: admin
X-Cbc-Timestamp: 1792382460
X-Cbc-Nonce: 7c1e9a3b5d7f9b1d3f5a7c9e1b3d5f7a
X-Cbc-Sign-Alg: RSA-SHA256
X-Cbc-Signature: <base64>
{"coin":"btc"}
请求待签串(7 行,
\n连接,末尾无换行):
POST
<base_path>/v2/balance
hxgmau9imt86qky9
admin
1792382460
7c1e9a3b5d7f9b1d3f5a7c9e1b3d5f7a
<请求 body 原始字节的 SHA-256 小写 hex>
每个请求都要带下面 6 个 Header,Content-Type 为 application/json:
| Header | 必选 | 说明 |
|---|---|---|
| X-Cbc-App-Id | 是 | 商户 APP_ID |
| X-Cbc-Key-Version | 否 | 商户公钥版本:admin / read / 自定义版本,不传时按 admin 处理 |
| X-Cbc-Timestamp | 是 | Unix 秒级时间戳,与平台时间相差不能超过 300 秒 |
| X-Cbc-Nonce | 是 | 随机串,16–64 位,只允许字母、数字、_、-。须用安全随机数生成,每次请求都不同 |
| X-Cbc-Sign-Alg | 是 | 固定 RSA-SHA256 |
| X-Cbc-Signature | 是 | 对待签串的签名,标准 Base64 |
待签串由 7 行组成,用 \n 连接,末尾不加换行:
- HTTP 方法,固定
POST; - 完整请求路径:baseUrl 的路径部分(下称 base_path)加上接口路径,使用 URL escaped path,不含域名和 query。例如接口路径
/v2/balance对应<base_path>/v2/balance; X-Cbc-App-Id的值;X-Cbc-Key-Version的值,不传时为admin;X-Cbc-Timestamp的值;X-Cbc-Nonce的值;- 请求 body 原始字节的 SHA-256,小写 hex。
签名 = Base64(RSA_PKCS1v15_Sign(商户私钥, SHA-256, 待签串))。
- 请求体为 JSON 对象,不超过 1 MB。没有业务参数的接口发送
{}。 - 同一 APP_ID 在时间窗内重复使用同一个 nonce,返回 603。
响应验签
响应示例:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Request-ID: 4bf92f3577b34da6a3ce929d0e0e4736
X-Cbc-Timestamp: 1792382461
X-Cbc-Nonce: 3b5d7f9a1c3e5b7d9f1a3c5e7b9d1f3a
X-Cbc-Sign-Alg: RSA-SHA256
X-Cbc-Signature: <base64>
{"status":200,"msg":"Request succeeded","data":{"amount":"1.5","freeze_amount":"0","total":"1.5","chain_hot_amount":"1.5"},"date_time":"2026-10-21 10:01:01","time_stamp":1792382461}
响应待签串(4 行,
\n连接,末尾无换行):
1792382461
3b5d7f9a1c3e5b7d9f1a3c5e7b9d1f3a
RSA-SHA256
<响应 body 原始字节的 SHA-256 小写 hex>
平台用 X-Cbc-Timestamp、X-Cbc-Nonce、X-Cbc-Sign-Alg、X-Cbc-Signature 4 个响应头对整个响应 body 签名。待签串为 4 行:响应头的 timestamp、nonce、RSA-SHA256、响应 body 原始字节的 SHA-256 小写 hex。
- 响应带签名头时,必须先用平台公钥验签,通过后再解析 body。验签失败应丢弃该响应。
- 验签阶段就失败的请求(如 601–606、无效的 APP_ID)返回的响应不带签名头,body 只能用于排查,不能作为业务结果。
- 每个响应都带
X-Request-ID(32 位小写 hex),由平台生成。排查问题时请提供这个值。
回调与复核签名
回调请求示例:
POST <商户提供的回调地址>
Content-Type: application/json
X-Cbc-Timestamp: 1792382460
X-Cbc-Nonce: 9f2c4e6a8b0d1f3e5a7c9e1b3d5f7a9c
X-Cbc-Sign-Alg: RSA-SHA256
X-Cbc-Signature: <base64>
{"data":{ ...各通知接口的字段... }}
平台发给商户的结果通知、提现订单二次复核和兑换订单二次复核,body 为 {"data":{...}},签名放在 4 个 Header 中:
| Header | 说明 |
|---|---|
| X-Cbc-Timestamp | Unix 秒级时间戳 |
| X-Cbc-Nonce | 随机串,32 位小写 hex |
| X-Cbc-Sign-Alg | 固定 RSA-SHA256 |
| X-Cbc-Signature | 对待签串的签名,标准 Base64 |
待签串与响应相同,为 4 行:timestamp、nonce、RSA-SHA256、请求 body 原始字节的 SHA-256 小写 hex。
接收端校验步骤:
- 4 个 Header 齐全,
X-Cbc-Sign-Alg为RSA-SHA256; X-Cbc-Timestamp与当前时间相差不超过 300 秒;- 用平台公钥验签(提现、兑换复核用平台风控公钥),参与摘要的必须是收到的 body 原始字节;
- nonce 在 300 秒内未出现过(建议缓存 660 秒);
- 以上都通过后再解析 body,处理业务并应答。
- 平台每次发送(包括重试)都会重新生成时间戳、nonce 和签名。
- 结果通知的成功应答与 v1 相同,见各通知接口。
- 签名版本由平台按商户配置,见从 v1 迁移到 v2。
用 fixture 自检
测试公钥(仅用于联调,不能用于生产):
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqiuoVcSN40UbFXjL7pT5
qbTE8xF7aQPCXhcytN8vqtHjDxd0Zjpx1oIkX456njAG68LxWCGba6LPxY+U7hGs
pCJju3iDivZyTncXz5xNm2H18PoEFSuV1IGredG5yetyChZFaNXoihdHN2hnMRvu
yPAT8U/buy+pI9AqH3J+W+Td9gZnswj1O3zQeerwj9q0CJCKXsRm+eBMb6h5z+yM
6GkXbNq4IFTiEUQMZYG+NxTRMrjLCZFLpu3C7spPdgXUOmuu2S3L6TxMq6BD8umm
OF9vvNV2GEmO4JFlJ6aYBiT0yPZ6K7wfCFgLbWuqYBk/1JKKoJx8eX7sJFypJLmW
sQIDAQAB
-----END PUBLIC KEY-----
请求:路径为
/v2/balance(base_path 为空),body 为{"coin":"btc"},待签串与签名:
POST
/v2/balance
demo-app
admin
1785340800
0123456789abcdef
0fe0ec658fa6fbb82bb702e898638326531ec4bc15056d40d94bbcc6a2266575
o/6sZdMMsV+I9UdWG+VH69CJ+Oop98cFVAfddS9q7ruj7pOKQbKDpSyXOYWF6FaeN8G2YOgYX7CeZR/cdE2PxYO29tV2cRpuM35oAL5wXde6uUU3CC506MOG/2btS9JLqOo77zBozj8d3T9yeWdmMHKTBeA/wEnHg9DqN03U88xk88Aq65/F4Ae3Of8jjw7ex8ejpp1ZZ04l4YZySyMXyc3G+UMzIYG7vmODSL9bsBuxtn0v5DWQ2Xyy2ZmF7FrlIWgJg0HRpUZUHOda/Pg8D2EkDBbnPavzz/x00xKlGJPmV4c8aoz/kP/VccFxBUbVvPYS/vyhl946Ve+OYIWjfA==
响应 / 回调:body 为
{"data":{"order_id":"1","amount":"1.5"}},待签串与签名:
1785340800
abcdef0123456789
RSA-SHA256
631af6d41ca0da36316c0d6ad0df8e338c23a9878548d5ee6831df183e70e25e
gcvD6paex+8LZZdtsuZ/251TzIIrDFChucvsUWj2V+Ls6f8uwgS7WJvQxBqx+b7n4eEBwyt/oYVxxBHk1K88v3wIweyrv+dqc3e7iHDlWJNFZE8oRsjGZCEzbBr0Trc9bqJwCqMiK0uosV9xcOVy6eDbqx7l8NDYaKz/9rWpD5aF/xhgQiCSO4WzhFenkWk0cnXwLX+gFU6NM2c3hmNDvY+QexWyxLYri/PYpXhFpDt/ethCtmXSyXuhu2iIef7Ijb1u3pApe2s9Ghx2P33TIY/+YDATjv5+nhhdRJYflL99odVHQA+pYwo8oIRibsTDdyadoV7D0d4Ly8uQ0OUYhQ==
右侧给出一把 2048 位测试公钥,以及一组固定的请求、响应待签串和对应签名。接入时:
- 用请求示例里的字段拼出待签串,应与右侧逐字节一致;
- 用测试公钥验证右侧两条签名,都应通过(响应验签时跳过 300 秒时间窗)。
两项都通过,说明待签串拼接、SHA-256 摘要和 RSA 实现与平台一致。该密钥仅用于联调,不能当作生产密钥。
客户端示例
// Go 1.18+,仅依赖标准库
//
// 调用接口:
// client, err := cbc.NewClient("<baseUrl>", "hxgmau9imt86qky9", "admin", merchantPrivateKeyPEM, platformPublicKeyPEM)
// resp, err := client.Post("/v2/balance", map[string]any{"coin": "btc"})
//
// 接收回调(net/http):
// body, _ := io.ReadAll(r.Body)
// if err := cbc.VerifyBody(r.Header, body, client.PlatformKey, true); err != nil { /* 拒绝 */ }
// // 按 X-Cbc-Nonce 去重后再解析 body
package cbc
import (
"bytes"
"crypto"
"crypto/rand"
"crypto/rsa"
"crypto/sha256"
"crypto/x509"
"encoding/base64"
"encoding/hex"
"encoding/json"
"encoding/pem"
"errors"
"fmt"
"io"
"net/http"
"net/url"
"strconv"
"strings"
"time"
)
const (
SignAlg = "RSA-SHA256"
TimeWindow = 300 * time.Second
)
// Client 调用 CipherBC API v2:签名请求,并用平台公钥验证响应。
type Client struct {
BaseURL string // 平台提供的 baseUrl
AppID string
KeyVersion string // 默认 admin
PrivateKey *rsa.PrivateKey // 商户私钥(PKCS#8)
PlatformKey *rsa.PublicKey // 平台公钥(PKIX)
HTTP *http.Client
basePath string // BaseURL 的路径部分(base_path)
}
func NewClient(baseURL, appID, keyVersion, merchantPrivateKeyPEM, platformPublicKeyPEM string) (*Client, error) {
priv, err := ParsePrivateKey(merchantPrivateKeyPEM)
if err != nil {
return nil, err
}
pub, err := ParsePublicKey(platformPublicKeyPEM)
if err != nil {
return nil, err
}
u, err := url.Parse(strings.TrimRight(baseURL, "/"))
if err != nil {
return nil, err
}
if keyVersion == "" {
keyVersion = "admin"
}
return &Client{
BaseURL: strings.TrimRight(baseURL, "/"), AppID: appID, KeyVersion: keyVersion,
PrivateKey: priv, PlatformKey: pub, HTTP: &http.Client{Timeout: 30 * time.Second},
basePath: u.EscapedPath(),
}, nil
}
// Post 发送请求,返回验签通过的响应 body。
// path 为接口路径,如 /v2/balance;params 为业务参数。
func (c *Client) Post(path string, params any) ([]byte, error) {
if params == nil {
params = map[string]any{}
}
body, err := json.Marshal(params)
if err != nil {
return nil, err
}
timestamp := strconv.FormatInt(time.Now().Unix(), 10)
nonce := NewNonce()
// 待签串用完整请求路径:base_path + path
canonical := RequestCanonical("POST", c.basePath+path, c.AppID, c.KeyVersion, timestamp, nonce, body)
signature, err := Sign(canonical, c.PrivateKey)
if err != nil {
return nil, err
}
// 发送的必须是参与签名的 body 原始字节
req, err := http.NewRequest(http.MethodPost, c.BaseURL+path, bytes.NewReader(body))
if err != nil {
return nil, err
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-Cbc-App-Id", c.AppID)
req.Header.Set("X-Cbc-Key-Version", c.KeyVersion)
req.Header.Set("X-Cbc-Timestamp", timestamp)
req.Header.Set("X-Cbc-Nonce", nonce)
req.Header.Set("X-Cbc-Sign-Alg", SignAlg)
req.Header.Set("X-Cbc-Signature", signature)
resp, err := c.HTTP.Do(req)
if err != nil {
return nil, err
}
defer resp.Body.Close()
respBody, err := io.ReadAll(resp.Body)
if err != nil {
return nil, err
}
if resp.Header.Get("X-Cbc-Signature") == "" {
// 验签前就失败的请求(如 601–606)没有签名头,body 只能用于排查
return respBody, fmt.Errorf("unsigned response, X-Request-ID=%s: %s", resp.Header.Get("X-Request-ID"), respBody)
}
if err := VerifyBody(resp.Header, respBody, c.PlatformKey, false); err != nil {
return nil, err
}
return respBody, nil
}
// RequestCanonical 请求待签串:7 行,\n 连接,末尾无换行。
func RequestCanonical(method, path, appID, keyVersion, timestamp, nonce string, body []byte) string {
return strings.Join([]string{method, path, appID, keyVersion, timestamp, nonce, Sha256Hex(body)}, "\n")
}
// BodyCanonical 响应、回调、复核的待签串:4 行,\n 连接,末尾无换行。
func BodyCanonical(timestamp, nonce string, body []byte) string {
return strings.Join([]string{timestamp, nonce, SignAlg, Sha256Hex(body)}, "\n")
}
// VerifyBody 校验响应、回调或复核请求的 4 个签名头。
// checkTime 为 true 时同时校验 300 秒时间窗(接收回调、复核请求时使用)。
// 通过后调用方还应按 X-Cbc-Nonce 去重,再解析 body。
func VerifyBody(header http.Header, body []byte, platformKey *rsa.PublicKey, checkTime bool) error {
timestamp := header.Get("X-Cbc-Timestamp")
nonce := header.Get("X-Cbc-Nonce")
signature := header.Get("X-Cbc-Signature")
if timestamp == "" || nonce == "" || signature == "" {
return errors.New("missing signature headers")
}
if header.Get("X-Cbc-Sign-Alg") != SignAlg {
return errors.New("unsupported X-Cbc-Sign-Alg")
}
if checkTime {
ts, err := strconv.ParseInt(timestamp, 10, 64)
if err != nil {
return errors.New("invalid X-Cbc-Timestamp")
}
if d := time.Since(time.Unix(ts, 0)); d > TimeWindow || d < -TimeWindow {
return errors.New("X-Cbc-Timestamp outside 300s window")
}
}
return Verify(BodyCanonical(timestamp, nonce, body), signature, platformKey)
}
// SignBody 对要发出的 body 签名,返回 4 个签名头(如提现复核的响应)。
// 签名后原样发送 body,不要重新序列化。
func SignBody(body []byte, privateKey *rsa.PrivateKey) (map[string]string, error) {
timestamp := strconv.FormatInt(time.Now().Unix(), 10)
nonce := NewNonce()
signature, err := Sign(BodyCanonical(timestamp, nonce, body), privateKey)
if err != nil {
return nil, err
}
return map[string]string{
"X-Cbc-Timestamp": timestamp,
"X-Cbc-Nonce": nonce,
"X-Cbc-Sign-Alg": SignAlg,
"X-Cbc-Signature": signature,
}, nil
}
// Sign = Base64(RSA_PKCS1v15_Sign(SHA-256(canonical)))
func Sign(canonical string, key *rsa.PrivateKey) (string, error) {
digest := sha256.Sum256([]byte(canonical))
sig, err := rsa.SignPKCS1v15(rand.Reader, key, crypto.SHA256, digest[:])
if err != nil {
return "", err
}
return base64.StdEncoding.EncodeToString(sig), nil
}
func Verify(canonical, signature string, key *rsa.PublicKey) error {
sig, err := base64.StdEncoding.DecodeString(signature)
if err != nil {
return err
}
digest := sha256.Sum256([]byte(canonical))
return rsa.VerifyPKCS1v15(key, crypto.SHA256, digest[:], sig)
}
func Sha256Hex(b []byte) string {
sum := sha256.Sum256(b)
return hex.EncodeToString(sum[:])
}
// NewNonce 返回 32 位小写 hex 随机串
func NewNonce() string {
b := make([]byte, 16)
if _, err := rand.Read(b); err != nil {
panic(err)
}
return hex.EncodeToString(b)
}
func ParsePrivateKey(pemStr string) (*rsa.PrivateKey, error) {
block, _ := pem.Decode([]byte(pemStr))
if block == nil {
return nil, errors.New("invalid private key PEM")
}
key, err := x509.ParsePKCS8PrivateKey(block.Bytes)
if err != nil {
return nil, err
}
rsaKey, ok := key.(*rsa.PrivateKey)
if !ok {
return nil, errors.New("not an RSA private key")
}
return rsaKey, nil
}
func ParsePublicKey(pemStr string) (*rsa.PublicKey, error) {
block, _ := pem.Decode([]byte(pemStr))
if block == nil {
return nil, errors.New("invalid public key PEM")
}
key, err := x509.ParsePKIXPublicKey(block.Bytes)
if err != nil {
return nil, err
}
rsaKey, ok := key.(*rsa.PublicKey)
if !ok {
return nil, errors.New("not an RSA public key")
}
return rsaKey, nil
}
<?php
// 调用接口:
// $client = new CbcClient('<baseUrl>', 'hxgmau9imt86qky9', 'admin', $merchantPrivateKeyPem, $platformPublicKeyPem);
// $resp = $client->post('/v2/balance', ['coin' => 'btc']);
//
// 接收回调:
// $body = file_get_contents('php://input');
// $headers = array_change_key_case(getallheaders(), CASE_LOWER);
// CbcClient::verifyBody($headers, $body, $platformPublicKeyPem, true); // 失败时抛出异常
// // 按 X-Cbc-Nonce 去重后再 json_decode($body, true)
// PHP 7.4+,需要 openssl、curl 扩展
class CbcClient
{
const SIGN_ALG = 'RSA-SHA256';
const TIME_WINDOW = 300; // 秒
private $baseUrl;
private $basePath; // $baseUrl 的路径部分(base_path)
private $appId;
private $keyVersion;
private $privateKey; // 商户私钥(PKCS#8 PEM)
private $platformKey; // 平台公钥(PKIX PEM)
// $baseUrl 由平台提供
public function __construct($baseUrl, $appId, $keyVersion, $merchantPrivateKeyPem, $platformPublicKeyPem)
{
$this->baseUrl = rtrim($baseUrl, '/');
$this->basePath = (string)parse_url($this->baseUrl, PHP_URL_PATH);
$this->appId = $appId;
$this->keyVersion = $keyVersion ?: 'admin';
$this->privateKey = $merchantPrivateKeyPem;
$this->platformKey = $platformPublicKeyPem;
}
// $path 为接口路径,如 /v2/balance;$params 为业务参数。返回验签通过的响应数组。
public function post($path, array $params = [])
{
// 无参数时发送 {},不要发送 []
$body = empty($params) ? '{}' : json_encode($params, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
$timestamp = (string)time();
$nonce = self::newNonce();
// 待签串用完整请求路径:base_path + path
$canonical = self::requestCanonical('POST', $this->basePath . $path, $this->appId, $this->keyVersion, $timestamp, $nonce, $body);
$respHeaders = [];
$ch = curl_init($this->baseUrl . $path);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $body, // 发送的必须是参与签名的 body 原始字节
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'X-Cbc-App-Id: ' . $this->appId,
'X-Cbc-Key-Version: ' . $this->keyVersion,
'X-Cbc-Timestamp: ' . $timestamp,
'X-Cbc-Nonce: ' . $nonce,
'X-Cbc-Sign-Alg: ' . self::SIGN_ALG,
'X-Cbc-Signature: ' . self::sign($canonical, $this->privateKey),
],
CURLOPT_HEADERFUNCTION => function ($ch, $line) use (&$respHeaders) {
$parts = explode(':', $line, 2);
if (count($parts) == 2) {
$respHeaders[strtolower(trim($parts[0]))] = trim($parts[1]);
}
return strlen($line);
},
]);
$respBody = curl_exec($ch);
if ($respBody === false) {
throw new RuntimeException(curl_error($ch));
}
curl_close($ch);
if (empty($respHeaders['x-cbc-signature'])) {
// 验签前就失败的请求(如 601–606)没有签名头,body 只能用于排查
$requestId = isset($respHeaders['x-request-id']) ? $respHeaders['x-request-id'] : '';
throw new RuntimeException("unsigned response, X-Request-ID={$requestId}: {$respBody}");
}
self::verifyBody($respHeaders, $respBody, $this->platformKey, false);
return json_decode($respBody, true);
}
// 请求待签串:7 行,\n 连接,末尾无换行
public static function requestCanonical($method, $path, $appId, $keyVersion, $timestamp, $nonce, $body)
{
return implode("\n", [$method, $path, $appId, $keyVersion, $timestamp, $nonce, hash('sha256', $body)]);
}
// 响应、回调、复核的待签串:4 行,\n 连接,末尾无换行
public static function bodyCanonical($timestamp, $nonce, $body)
{
return implode("\n", [$timestamp, $nonce, self::SIGN_ALG, hash('sha256', $body)]);
}
// 校验响应、回调或复核请求的 4 个签名头,失败时抛出异常。
// $headers 的 key 为小写 Header 名;$checkTime 为 true 时同时校验 300 秒时间窗(接收回调、复核请求时使用)。
// 通过后调用方还应按 X-Cbc-Nonce 去重,再解析 body。
public static function verifyBody(array $headers, $body, $platformPublicKeyPem, $checkTime)
{
$timestamp = isset($headers['x-cbc-timestamp']) ? $headers['x-cbc-timestamp'] : '';
$nonce = isset($headers['x-cbc-nonce']) ? $headers['x-cbc-nonce'] : '';
$signature = isset($headers['x-cbc-signature']) ? $headers['x-cbc-signature'] : '';
if ($timestamp === '' || $nonce === '' || $signature === '') {
throw new RuntimeException('missing signature headers');
}
if (!isset($headers['x-cbc-sign-alg']) || $headers['x-cbc-sign-alg'] !== self::SIGN_ALG) {
throw new RuntimeException('unsupported X-Cbc-Sign-Alg');
}
if ($checkTime && (!ctype_digit($timestamp) || abs(time() - (int)$timestamp) > self::TIME_WINDOW)) {
throw new RuntimeException('X-Cbc-Timestamp outside 300s window');
}
if (!self::verify(self::bodyCanonical($timestamp, $nonce, $body), $signature, $platformPublicKeyPem)) {
throw new RuntimeException('signature verification failed');
}
}
// 对要发出的 body 签名,返回 4 个签名头(如提现复核的响应)。签名后原样发送 body。
public static function signBody($body, $privateKeyPem)
{
$timestamp = (string)time();
$nonce = self::newNonce();
return [
'X-Cbc-Timestamp' => $timestamp,
'X-Cbc-Nonce' => $nonce,
'X-Cbc-Sign-Alg' => self::SIGN_ALG,
'X-Cbc-Signature' => self::sign(self::bodyCanonical($timestamp, $nonce, $body), $privateKeyPem),
];
}
// Base64(RSA_PKCS1v15_Sign(SHA-256(canonical)))
public static function sign($canonical, $privateKeyPem)
{
if (!openssl_sign($canonical, $signature, $privateKeyPem, OPENSSL_ALGO_SHA256)) {
throw new RuntimeException('sign failed: ' . openssl_error_string());
}
return base64_encode($signature);
}
public static function verify($canonical, $signature, $publicKeyPem)
{
return openssl_verify($canonical, base64_decode($signature), $publicKeyPem, OPENSSL_ALGO_SHA256) === 1;
}
// 32 位小写 hex 随机串
public static function newNonce()
{
return bin2hex(random_bytes(16));
}
}
// 调用接口:
// const client = new CbcClient('<baseUrl>', 'hxgmau9imt86qky9', 'admin', merchantPrivateKeyPem, platformPublicKeyPem);
// const resp = await client.post('/v2/balance', { coin: 'btc' });
//
// 接收回调(Express,需 express.raw({ type: 'application/json' }) 保留原始 body):
// verifyBody((name) => req.get(name), req.body, platformPublicKeyPem, true); // 失败时抛出异常
// // 按 X-Cbc-Nonce 去重后再 JSON.parse(req.body)
// Node.js 18+
import crypto from 'node:crypto';
export const SIGN_ALG = 'RSA-SHA256';
export const TIME_WINDOW = 300; // 秒
export const sha256Hex = (buf) => crypto.createHash('sha256').update(buf).digest('hex');
export const newNonce = () => crypto.randomBytes(16).toString('hex'); // 32 位小写 hex
// 请求待签串:7 行,\n 连接,末尾无换行
export function requestCanonical(method, path, appId, keyVersion, timestamp, nonce, body) {
return [method, path, appId, keyVersion, timestamp, nonce, sha256Hex(body)].join('\n');
}
// 响应、回调、复核的待签串:4 行,\n 连接,末尾无换行
export function bodyCanonical(timestamp, nonce, body) {
return [timestamp, nonce, SIGN_ALG, sha256Hex(body)].join('\n');
}
// Base64(RSA_PKCS1v15_Sign(SHA-256(canonical)))
export function sign(canonical, privateKeyPem) {
return crypto.sign('sha256', Buffer.from(canonical), privateKeyPem).toString('base64');
}
export function verify(canonical, signature, publicKeyPem) {
return crypto.verify('sha256', Buffer.from(canonical), publicKeyPem, Buffer.from(signature, 'base64'));
}
// 校验响应、回调或复核请求的 4 个签名头,失败时抛出异常。
// getHeader(name) 返回 Header 值;checkTime 为 true 时同时校验 300 秒时间窗(接收回调、复核请求时使用)。
// 通过后调用方还应按 X-Cbc-Nonce 去重,再解析 body。
export function verifyBody(getHeader, body, platformPublicKeyPem, checkTime) {
const timestamp = getHeader('X-Cbc-Timestamp');
const nonce = getHeader('X-Cbc-Nonce');
const signature = getHeader('X-Cbc-Signature');
if (!timestamp || !nonce || !signature) throw new Error('missing signature headers');
if (getHeader('X-Cbc-Sign-Alg') !== SIGN_ALG) throw new Error('unsupported X-Cbc-Sign-Alg');
if (checkTime) {
const ts = Number(timestamp);
if (!Number.isInteger(ts) || Math.abs(Date.now() / 1000 - ts) > TIME_WINDOW) {
throw new Error('X-Cbc-Timestamp outside 300s window');
}
}
if (!verify(bodyCanonical(timestamp, nonce, body), signature, platformPublicKeyPem)) {
throw new Error('signature verification failed');
}
}
// 对要发出的 body 签名,返回 4 个签名头(如提现复核的响应)。签名后原样发送 body。
export function signBody(body, privateKeyPem) {
const timestamp = String(Math.floor(Date.now() / 1000));
const nonce = newNonce();
return {
'X-Cbc-Timestamp': timestamp,
'X-Cbc-Nonce': nonce,
'X-Cbc-Sign-Alg': SIGN_ALG,
'X-Cbc-Signature': sign(bodyCanonical(timestamp, nonce, body), privateKeyPem),
};
}
export class CbcClient {
// baseUrl 由平台提供;merchantPrivateKey 为 PKCS#8 PEM,platformPublicKey 为 PKIX PEM
constructor(baseUrl, appId, keyVersion, merchantPrivateKey, platformPublicKey) {
this.baseUrl = baseUrl.replace(/\/+$/, '');
this.basePath = new URL(this.baseUrl).pathname.replace(/\/+$/, ''); // baseUrl 的路径部分(base_path)
this.appId = appId;
this.keyVersion = keyVersion || 'admin';
this.privateKey = merchantPrivateKey;
this.platformKey = platformPublicKey;
}
// path 为接口路径,如 /v2/balance;params 为业务参数。返回验签通过的响应 JSON。
async post(path, params = {}) {
const body = Buffer.from(JSON.stringify(params));
const timestamp = String(Math.floor(Date.now() / 1000));
const nonce = newNonce();
// 待签串用完整请求路径:base_path + path
const canonical = requestCanonical('POST', this.basePath + path, this.appId, this.keyVersion, timestamp, nonce, body);
// 发送的必须是参与签名的 body 原始字节
const resp = await fetch(this.baseUrl + path, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Cbc-App-Id': this.appId,
'X-Cbc-Key-Version': this.keyVersion,
'X-Cbc-Timestamp': timestamp,
'X-Cbc-Nonce': nonce,
'X-Cbc-Sign-Alg': SIGN_ALG,
'X-Cbc-Signature': sign(canonical, this.privateKey),
},
body,
});
const respBody = Buffer.from(await resp.arrayBuffer());
if (!resp.headers.get('X-Cbc-Signature')) {
// 验签前就失败的请求(如 601–606)没有签名头,body 只能用于排查
throw new Error(`unsigned response, X-Request-ID=${resp.headers.get('X-Request-ID')}: ${respBody}`);
}
verifyBody((name) => resp.headers.get(name), respBody, this.platformKey, false);
return JSON.parse(respBody.toString('utf8'));
}
}
// 调用接口:
// CbcClient client = new CbcClient("<baseUrl>", "hxgmau9imt86qky9", "admin", merchantPrivateKeyPem, platformPublicKeyPem);
// String resp = client.post("/v2/balance", Map.of("coin", "btc"));
//
// 接收回调:读取原始 body 字节,取出 4 个签名头放进 Map 后调用
// CbcClient.verifyBody(headers, rawBody, CbcClient.parsePublicKey(platformPublicKeyPem), true); // 失败时抛出异常
// // 按 X-Cbc-Nonce 去重后再解析 body
// Java 11+,无第三方依赖
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpHeaders;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.security.KeyFactory;
import java.security.MessageDigest;
import java.security.PrivateKey;
import java.security.PublicKey;
import java.security.SecureRandom;
import java.security.Signature;
import java.security.spec.PKCS8EncodedKeySpec;
import java.security.spec.X509EncodedKeySpec;
import java.time.Duration;
import java.util.Base64;
import java.util.Collection;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.StringJoiner;
public class CbcClient {
public static final String SIGN_ALG = "RSA-SHA256";
public static final long TIME_WINDOW = 300; // 秒
private static final SecureRandom RANDOM = new SecureRandom();
private final String baseUrl;
private final String basePath; // baseUrl 的路径部分(base_path)
private final String appId;
private final String keyVersion;
private final PrivateKey privateKey; // 商户私钥(PKCS#8)
private final PublicKey platformKey; // 平台公钥(PKIX)
private final HttpClient http = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(10)).build();
// baseUrl 由平台提供
public CbcClient(String baseUrl, String appId, String keyVersion,
String merchantPrivateKeyPem, String platformPublicKeyPem) throws Exception {
this.baseUrl = baseUrl.replaceAll("/+$", "");
String p = URI.create(this.baseUrl).getRawPath();
this.basePath = p == null ? "" : p;
this.appId = appId;
this.keyVersion = (keyVersion == null || keyVersion.isEmpty()) ? "admin" : keyVersion;
this.privateKey = parsePrivateKey(merchantPrivateKeyPem);
this.platformKey = parsePublicKey(platformPublicKeyPem);
}
// path 为接口路径,如 /v2/balance;params 为业务参数,值可以是 String、Number、Boolean、Map、List。
// 返回验签通过的响应 body。
public String post(String path, Map<String, ?> params) throws Exception {
return post(path, toJson(params));
}
// path 为接口路径,如 /v2/balance;jsonBody 为业务参数 JSON,无参数时传 "{}"。
// 返回验签通过的响应 body。
public String post(String path, String jsonBody) throws Exception {
byte[] body = jsonBody.getBytes(StandardCharsets.UTF_8);
String timestamp = String.valueOf(System.currentTimeMillis() / 1000);
String nonce = newNonce();
// 待签串用完整请求路径:base_path + path
String canonical = requestCanonical("POST", basePath + path, appId, keyVersion, timestamp, nonce, body);
// 发送的必须是参与签名的 body 原始字节
HttpRequest req = HttpRequest.newBuilder(URI.create(baseUrl + path))
.timeout(Duration.ofSeconds(30))
.header("Content-Type", "application/json")
.header("X-Cbc-App-Id", appId)
.header("X-Cbc-Key-Version", keyVersion)
.header("X-Cbc-Timestamp", timestamp)
.header("X-Cbc-Nonce", nonce)
.header("X-Cbc-Sign-Alg", SIGN_ALG)
.header("X-Cbc-Signature", sign(canonical, privateKey))
.POST(HttpRequest.BodyPublishers.ofByteArray(body))
.build();
HttpResponse<byte[]> resp = http.send(req, HttpResponse.BodyHandlers.ofByteArray());
HttpHeaders h = resp.headers();
String respBody = new String(resp.body(), StandardCharsets.UTF_8);
if (h.firstValue("X-Cbc-Signature").isEmpty()) {
// 验签前就失败的请求(如 601–606)没有签名头,body 只能用于排查
throw new IllegalStateException("unsigned response, X-Request-ID="
+ h.firstValue("X-Request-ID").orElse("") + ": " + respBody);
}
Map<String, String> sigHeaders = new LinkedHashMap<>();
for (String name : new String[]{"X-Cbc-Timestamp", "X-Cbc-Nonce", "X-Cbc-Sign-Alg", "X-Cbc-Signature"}) {
sigHeaders.put(name, h.firstValue(name).orElse(null));
}
verifyBody(sigHeaders, resp.body(), platformKey, false);
return respBody;
}
// 请求待签串:7 行,\n 连接,末尾无换行
public static String requestCanonical(String method, String path, String appId, String keyVersion,
String timestamp, String nonce, byte[] body) throws Exception {
return String.join("\n", method, path, appId, keyVersion, timestamp, nonce, sha256Hex(body));
}
// 响应、回调、复核的待签串:4 行,\n 连接,末尾无换行
public static String bodyCanonical(String timestamp, String nonce, byte[] body) throws Exception {
return String.join("\n", timestamp, nonce, SIGN_ALG, sha256Hex(body));
}
// 校验响应、回调或复核请求的 4 个签名头,失败时抛出异常。
// headers 的 key 为 X-Cbc-Timestamp 等 Header 名;checkTime 为 true 时同时校验 300 秒时间窗(接收回调、复核请求时使用)。
// 通过后调用方还应按 X-Cbc-Nonce 去重,再解析 body。
public static void verifyBody(Map<String, String> headers, byte[] body, PublicKey platformKey,
boolean checkTime) throws Exception {
String timestamp = headers.get("X-Cbc-Timestamp");
String nonce = headers.get("X-Cbc-Nonce");
String signature = headers.get("X-Cbc-Signature");
if (isEmpty(timestamp) || isEmpty(nonce) || isEmpty(signature)) {
throw new SecurityException("missing signature headers");
}
if (!SIGN_ALG.equals(headers.get("X-Cbc-Sign-Alg"))) {
throw new SecurityException("unsupported X-Cbc-Sign-Alg");
}
if (checkTime && Math.abs(System.currentTimeMillis() / 1000 - Long.parseLong(timestamp)) > TIME_WINDOW) {
throw new SecurityException("X-Cbc-Timestamp outside 300s window");
}
if (!verify(bodyCanonical(timestamp, nonce, body), signature, platformKey)) {
throw new SecurityException("signature verification failed");
}
}
// 对要发出的 body 签名,返回 4 个签名头(如提现复核的响应)。签名后原样发送 body。
public static Map<String, String> signBody(byte[] body, PrivateKey privateKey) throws Exception {
String timestamp = String.valueOf(System.currentTimeMillis() / 1000);
String nonce = newNonce();
Map<String, String> headers = new LinkedHashMap<>();
headers.put("X-Cbc-Timestamp", timestamp);
headers.put("X-Cbc-Nonce", nonce);
headers.put("X-Cbc-Sign-Alg", SIGN_ALG);
headers.put("X-Cbc-Signature", sign(bodyCanonical(timestamp, nonce, body), privateKey));
return headers;
}
// Base64(RSA_PKCS1v15_Sign(SHA-256(canonical)))
public static String sign(String canonical, PrivateKey key) throws Exception {
Signature s = Signature.getInstance("SHA256withRSA");
s.initSign(key);
s.update(canonical.getBytes(StandardCharsets.UTF_8));
return Base64.getEncoder().encodeToString(s.sign());
}
public static boolean verify(String canonical, String signature, PublicKey key) throws Exception {
Signature s = Signature.getInstance("SHA256withRSA");
s.initVerify(key);
s.update(canonical.getBytes(StandardCharsets.UTF_8));
return s.verify(Base64.getDecoder().decode(signature));
}
public static String sha256Hex(byte[] data) throws Exception {
return hex(MessageDigest.getInstance("SHA-256").digest(data));
}
// 32 位小写 hex 随机串
public static String newNonce() {
byte[] b = new byte[16];
RANDOM.nextBytes(b);
return hex(b);
}
public static PrivateKey parsePrivateKey(String pem) throws Exception {
return KeyFactory.getInstance("RSA").generatePrivate(new PKCS8EncodedKeySpec(pemBody(pem)));
}
public static PublicKey parsePublicKey(String pem) throws Exception {
return KeyFactory.getInstance("RSA").generatePublic(new X509EncodedKeySpec(pemBody(pem)));
}
// 最小 JSON 序列化;项目里已有 Jackson、Gson 时可以替换
public static String toJson(Object v) {
if (v == null) {
return "null";
}
if (v instanceof String) {
return quote((String) v);
}
if (v instanceof Number || v instanceof Boolean) {
return v.toString();
}
if (v instanceof Map) {
StringJoiner j = new StringJoiner(",", "{", "}");
for (Map.Entry<?, ?> e : ((Map<?, ?>) v).entrySet()) {
j.add(quote(String.valueOf(e.getKey())) + ":" + toJson(e.getValue()));
}
return j.toString();
}
if (v instanceof Collection) {
StringJoiner j = new StringJoiner(",", "[", "]");
for (Object o : (Collection<?>) v) {
j.add(toJson(o));
}
return j.toString();
}
throw new IllegalArgumentException("unsupported type: " + v.getClass());
}
private static String quote(String s) {
StringBuilder sb = new StringBuilder("\"");
for (char c : s.toCharArray()) {
if (c == '"' || c == '\\') {
sb.append('\\').append(c);
} else if (c < 0x20) {
sb.append(String.format("\\u%04x", (int) c));
} else {
sb.append(c);
}
}
return sb.append('"').toString();
}
private static byte[] pemBody(String pem) {
return Base64.getMimeDecoder().decode(pem.replaceAll("-----[A-Z ]+-----", ""));
}
private static String hex(byte[] b) {
StringBuilder sb = new StringBuilder(b.length * 2);
for (byte x : b) {
sb.append(String.format("%02x", x));
}
return sb.toString();
}
private static boolean isEmpty(String s) {
return s == null || s.isEmpty();
}
}
go、php、js、java 各一份完整客户端,均已用上面的 fixture 验证:
Post/post:签请求、发送、验响应,返回验签通过的响应 body;VerifyBody/verifyBody:校验响应、结果通知和复核请求的 4 个签名头,接收通知时打开 300 秒时间窗校验;SignBody/signBody:对要发出的 body 签名,用于提现、兑换复核的响应。
各接口的示例都调用这里的客户端,只写路径和业务参数。
密钥要求
- RSA 密钥不少于 2048 位。
- 公钥为 PKIX 格式(
-----BEGIN PUBLIC KEY-----),私钥为 PKCS#8 格式(-----BEGIN PRIVATE KEY-----)。 - 商户需要生成两对密钥,业务和风控分开,不能共用:
| 密钥对 | 用途 | 平台对应提供 |
|---|---|---|
| 业务密钥对 | 商户私钥签名所有 API 请求;商户公钥给平台验证请求 | 平台公钥,用于验证响应和结果通知 |
| 风控密钥对 | 商户风控私钥签名提现、兑换二次复核的响应;商户风控公钥给平台验证复核响应 | 平台风控公钥,用于验证提现、兑换二次复核请求 |
公私钥生成命令行
mkdir rsa_pem && cd rsa_pem
# 业务密钥对
# 生成私钥
openssl genrsa -out app_private_key.pem 2048
# 私钥转为 PKCS#8 格式
openssl pkcs8 -topk8 -inform PEM -in app_private_key.pem -outform PEM -nocrypt -out app_private_key_pkcs8.pem
# 根据私钥生成公钥
openssl rsa -in app_private_key.pem -pubout -out app_public_key.pem
# 风控密钥对
# 生成私钥
openssl genrsa -out risk_private_key.pem 2048
# 私钥转为 PKCS#8 格式
openssl pkcs8 -topk8 -inform PEM -in risk_private_key.pem -outform PEM -nocrypt -out risk_private_key_pkcs8.pem
# 根据私钥生成公钥
openssl rsa -in risk_private_key.pem -pubout -out risk_public_key.pem
在自己电脑的终端里依次执行下面的 OpenSSL 命令,就能生成业务、风控两对 2048 位密钥,不需要写代码。macOS、Linux 一般自带 OpenSSL,Windows 可在 Git Bash 中执行。右侧有同样的命令,可以直接复制。
- 创建并进入目录:
mkdir rsa_pem && cd rsa_pem - 生成业务密钥对:
- 生成私钥:
openssl genrsa -out app_private_key.pem 2048 - 私钥转为 PKCS#8 格式:
openssl pkcs8 -topk8 -inform PEM -in app_private_key.pem -outform PEM -nocrypt -out app_private_key_pkcs8.pem - 根据私钥生成公钥:
openssl rsa -in app_private_key.pem -pubout -out app_public_key.pem
- 生成私钥:
- 生成风控密钥对:
- 生成私钥:
openssl genrsa -out risk_private_key.pem 2048 - 私钥转为 PKCS#8 格式:
openssl pkcs8 -topk8 -inform PEM -in risk_private_key.pem -outform PEM -nocrypt -out risk_private_key_pkcs8.pem - 根据私钥生成公钥:
openssl rsa -in risk_private_key.pem -pubout -out risk_public_key.pem
- 生成私钥:
执行完成后,rsa_pem 目录里要用到的文件如下:
| 文件 | 说明 |
|---|---|
app_private_key_pkcs8.pem |
商户业务私钥(PKCS#8),配置到客户端,用于请求签名 |
app_public_key.pem |
商户业务公钥,提供给平台 |
risk_private_key_pkcs8.pem |
商户风控私钥(PKCS#8),配置到提现、兑换复核接口,用于复核响应签名 |
risk_public_key.pem |
商户风控公钥,提供给平台 |
两个私钥自行妥善保管,不要提供给任何人。两个公钥提供给平台时注明哪个是业务公钥、哪个是风控公钥。
公共信息说明
以下信息对所有接口均通用、后面每个接口不重复描述
接口地址
请求地址 = baseUrl + 接口路径。baseUrl 请联系客服获得,v1 与 v2 相同。文档中的接口路径(如 /v2/balance)都相对 baseUrl。baseUrl 中域名之后的路径部分记为 base_path,签名时待签串使用完整请求路径 <base_path>/v2/...。
生产环境
API接口地址请联系客服获得
测试环境
API接口地址请联系客服获得
请求公共 Header
| Header | 必选 | 案列 | 说明 |
|---|---|---|---|
| X-Cbc-App-Id | 是 | hxgmau9imt86qky9 | 商户号,具体对接时系统分配 |
| X-Cbc-Key-Version | 否 | admin | 秘钥版本号:admin / read / arbitrary-可以针对任意1-n个接口授权,默认 admin |
| X-Cbc-Timestamp | 是 | 1792382460 | 时间戳,Unix 秒,忽略时区 |
| X-Cbc-Nonce | 是 | 7c1e9a3b5d7f9b1d3f5a7c9e1b3d5f7a | 16–64 位随机串,每次请求唯一 |
| X-Cbc-Sign-Alg | 是 | RSA-SHA256 | 签名算法,固定值 |
| X-Cbc-Signature | 是 | Dr7MnhPYh… | 签名,见签名规则 |
响应 Header
| Header | 说明 |
|---|---|
| X-Request-ID | 请求 ID,32 位小写 hex,由平台生成。排查问题时请提供 |
| X-Cbc-Timestamp | 响应签名时间戳 |
| X-Cbc-Nonce | 响应签名随机串 |
| X-Cbc-Sign-Alg | 固定 RSA-SHA256 |
| X-Cbc-Signature | 响应签名。验签阶段就失败的响应不带签名头 |
公共返回参数
| 参数名 | 类型 | 说明 |
|---|---|---|
| status | integer | 状态码,200 表示成功,见全局状态码 |
| msg | string | 状态描述 |
| data | object | 业务数据;没有数据时为 null |
| date_time | string | 服务端时间,北京时间,格式 YYYY-MM-DD HH:mm:ss |
| time_stamp | integer | Unix 秒级时间戳 |
公共信息须知
| 名称 | 类型 | 案列 | 描述 |
|---|---|---|---|
| 时间1 | timeStamp | 1578829811 | UTC 时间统一时间不带时区 |
| 时间2 | DateTime | 2020-01-09 15:48:42 | 全局系统如果出现这种格式默认为北京时间 |
| 请求方式 | POST | — | 所有请求均为POST |
| 编码 | UTF-8 | — | 其他编码可能会产生乱码和错误 |
| 通信协议 | HTTPS | https | 目前仅支持HTTPS |
| 签名类型 | RSA-SHA256 | Dr7MnhPYh… | RSA 密钥不少于 2048 位,见签名规则 |
| 请求与返回 | JSON | — | 所有请求和响应参数都是JSON格式 |
| 金额参数注意 | string | — | 小数点后超8位,小数点前超12位无法通过,最后无效0要删除 |
接口清单
下表列出各章节的接口和路径,路径相对 baseUrl。
| 章节 | 接口 | 路径 |
|---|---|---|
| 地址 | 地址获取 | /v2/address/getBatch |
| 地址 | 地址列表 | /v2/address/list |
| 地址 | 类eos的地址+memo模式 | /v2/address/coinAccount |
| 地址 | 地址状态同步 | /v2/address/syncStatus |
| 地址 | 地址状态批量同步 | /v2/address/syncBatchStatus |
| 地址 | 地址验证 | /v2/address/verifyAddress |
| 地址 | 地址AML反洗钱风险验证 | /v2/address/verifyAml |
| 充值 | 充值列表 | /v2/receive/list |
| 充值 | 账户余额查询 | /v2/balance |
| 充值 | 充值结果回调通知 | 商户提供的回调地址 |
| 提现 | 提现申请 | /v2/transfer |
| 提现 | 提现列表 | /v2/transfer/list |
| 提现 | 提现结果回调通知 | 商户提供的回调地址 |
| 兑换 | 兑换申请 | /v2/exchange/index |
| 兑换 | 兑换账户充值 | /v2/exchange/transfer |
| 兑换 | 兑换汇率 | /v2/rate/exchange |
| 兑换 | 批量查询兑换汇率 | /v2/rate/exchangeBatch |
| 兑换 | 兑换余额查询 | /v2/balance/exchange |
| 兑换 | 兑换交易对查询 | /v2/exchange/coin |
| 兑换 | 兑换列表查询 | /v2/exchange/list |
| 兑换 | 兑换回调通知 | 商户提供的回调地址 |
| 统计 | 商家财务结算总账 | /v2/balance/generalAccount |
| 统计 | 商家充值/提现成功数量 | /v2/statistics/transfer |
| 风控回调 | 提现订单二次复核 | 商户提供的复核地址 |
| 风控回调 | 兑换订单二次复核 | 商户提供的复核地址 |
| 风控回调 | MPC订单复核接口 | 商户提供的复核地址 |
| 风控回调 | CoSigner-MPC订单复核接口 | 商户提供的复核地址 |
| H5充值 | 创建订单 | /v2/h5Order/create |
| H5充值 | 订单取消 | /v2/h5Order/cancel |
| H5充值 | 订单详情 | /v2/h5Order/detail |
| H5充值 | 订单回调通知 | 商户提供的回调地址 |
| 外部地址 | 新增外部地址 | /v2/outerAddress/add |
| 外部地址 | 删除外部地址 | /v2/outerAddress/delete |
| 外部地址 | 外部地址交易变动回调通知 | 商户提供的回调地址 |
| 其他 | 币种查询 | /v2/coin/list |
| 其他 | 币价汇率 | /v2/rate/index |
| 其他 | 币种对法币价格汇率 | /v2/rate/fiatCurrency |
| 其他 | 归集手续费计算 | /v2/balance/transactionFee |
| 其他 | 提现gas费预估查询 | /v2/transfer/transactionFee |
| 其他 | 退款记录列表 | /v2/refund/list |
| 其他 | 检测其账本记录的币种数量是否和其链上钱包的数据一致 | /v2/reconcile/balances |
| 其他 | 检测其某个账户地址的币种数量是否其链上数量一致 | /v2/reconcile/addressBalance |
| 其他 | 检测内部账本记录的提币数据是否和其钱包链上的数据一致 | /v2/reconcile/withdrawal |
- 平台发给商户的报文(结果通知、复核)用哪个版本,由商户的签名版本决定,见下一节。MPC 订单复核、CoSigner-MPC 订单复核仍为 v1,签名规则见 v1 文档。
从 v1 迁移到 v2
差异对照
| 项 | v1 | v2 |
|---|---|---|
| 路径 | /... |
/v2/...,4 组路径改为 lower camelCase,见下表 |
| 请求签名 | body 内 app_id、version、time、key_version、sign |
6 个 Header:X-Cbc-App-Id、X-Cbc-Key-Version、X-Cbc-Timestamp、X-Cbc-Nonce、X-Cbc-Sign-Alg、X-Cbc-Signature |
| 请求待签串 | 参数排序拼接,MD5 摘要 | 7 行:method、path、app_id、key_version、timestamp、nonce、body SHA-256 |
| 响应 | body 内 sign |
4 个响应 Header,待签串 4 行:timestamp、nonce、RSA-SHA256、body SHA-256 |
| 结果通知、提现与兑换复核 | body 内 sign |
body 为 {"data":{...}},签名放在 4 个 Header |
路径变化
| v1 | v2 |
|---|---|
/h5_order/create cancel detail |
/v2/h5Order/create cancel detail |
/outer_address/add delete |
/v2/outerAddress/add delete |
/rate/exchange_batch |
/v2/rate/exchangeBatch |
/rate/fiat_currency |
/v2/rate/fiatCurrency |
其余接口只是在路径前加 /v2,例如 /address/getBatch → /v2/address/getBatch。v1 与 v2 的 baseUrl 相同。
迁移步骤
- 请求侧:随时可以迁移,不需要通知平台。v2 请求不看商户的签名版本,使用同一把商户密钥,可以逐个接口切换。密钥须满足密钥要求,不足 2048 位的需先更换。
- 结果通知与复核:由平台按商户配置的签名版本统一切换。值为 v2 时,充值(到账、到账确认)、提现、兑换、H5 订单、外部地址交易结果通知,以及提现订单二次复核和兑换订单二次复核一起改用 v2;MPC 订单复核、CoSigner-MPC 订单复核仍为 v1。
- 回调接收端、提现复核接口和兑换复核接口(已开通兑换时)都改造完成后,再联系平台切换签名版本。需要回退时,三者一起回到 v1。
- 切换期间,接收端同时兼容两种格式,按请求格式回应:请求带
X-Cbc-Signature头时按 v2 处理,否则按 v1(body 内sign)处理。平台按每次发送时的商户版本选择格式,在途通知和重试从下一次发送起使用新格式。