Welcome to CipherBC API
Preparing for API
1 Register APP_ID
Contact customer service to register for APP_ID, and provide relevant qualification information. Example: Company Name, domain name, IP, first person in charge and other business information needed.
2 Provide a list of main chains and contract currencies that needs to be supported.
Coin require basic information such as coin address, main chain, precision, name and other relevant information will be provided to business coordinator.
3 Debugging API test environment
API adopting RSA2048bit for two-way signature verification to ensures the credibility of communication. Merchants are required to give the public key to the platform, where platform uses it to verify request parameters sent to the platform. Merchants need to obtain the platform public key in advance, which can be used to verify platform response.
Supported Coin
Signature Regulations
New merchants must use V2 signatures. V1 is no longer available to new merchants; existing merchants may continue to use V1.
This documentation uses v2 signatures. In v2, identity and signature travel in HTTP headers and the request body contains only business fields. The algorithm is always RSA-SHA256 (RSA PKCS#1 v1.5 + SHA-256) and signatures are standard Base64.
- Requests: the merchant signs with the merchant private key; the platform verifies with the merchant public key.
- Responses and result notifications: the platform signs with the platform private key; the merchant verifies with the platform public key.
- The withdrawal order 2nd review and exchange order 2nd review risk control APIs share a dedicated risk control key pair; see Risk control callback for details.
- Digests are computed over the raw bytes actually sent. Do not re-serialize the body after signing, or verification fails.
- The allowed clock skew is 300 seconds; keep your server clock synchronized.
Request signature
Request example:
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"}
Request canonical string (7 lines joined by
\n, no trailing newline):
POST
<base_path>/v2/balance
hxgmau9imt86qky9
admin
1792382460
7c1e9a3b5d7f9b1d3f5a7c9e1b3d5f7a
<lowercase hex SHA-256 of the raw request body bytes>
Every request carries the following 6 headers, with Content-Type: application/json:
| Header | Required | Description |
|---|---|---|
| X-Cbc-App-Id | Yes | Merchant APP_ID |
| X-Cbc-Key-Version | No | Merchant public key version: admin / read / custom version; admin when omitted |
| X-Cbc-Timestamp | Yes | Unix timestamp in seconds, within 300 seconds of platform time |
| X-Cbc-Nonce | Yes | Random string of 16–64 characters; only letters, digits, _ and -. Generate it with a secure random source; it must differ for every request |
| X-Cbc-Sign-Alg | Yes | Always RSA-SHA256 |
| X-Cbc-Signature | Yes | Signature of the canonical string, standard Base64 |
The canonical string has 7 lines joined by \n with no trailing newline:
- HTTP method, always
POST; - Full request path: the path part of baseUrl (base_path below) plus the API path, as the URL escaped path without host or query. For example, the API path
/v2/balancebecomes<base_path>/v2/balance; - Value of
X-Cbc-App-Id; - Value of
X-Cbc-Key-Version,adminwhen omitted; - Value of
X-Cbc-Timestamp; - Value of
X-Cbc-Nonce; - Lowercase hex SHA-256 of the raw request body bytes.
Signature = Base64(RSA_PKCS1v15_Sign(merchant private key, SHA-256, canonical string)).
- The request body is a JSON object of at most 1 MB. Send
{}for APIs without business parameters. - Reusing a nonce for the same APP_ID within the time window returns 603.
Response verification
Response example:
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}
Response canonical string (4 lines joined by
\n, no trailing newline):
1792382461
3b5d7f9a1c3e5b7d9f1a3c5e7b9d1f3a
RSA-SHA256
<lowercase hex SHA-256 of the raw response body bytes>
The platform signs the entire response body with 4 response headers: X-Cbc-Timestamp, X-Cbc-Nonce, X-Cbc-Sign-Alg and X-Cbc-Signature. The canonical string has 4 lines: the response header timestamp, nonce, RSA-SHA256, and the lowercase hex SHA-256 of the raw response body bytes.
- When a response carries signature headers, verify it with the platform public key before parsing the body. Discard the response if verification fails.
- Requests that fail during signature verification (such as 601–606 or an invalid APP_ID) get responses without signature headers. Use their body for troubleshooting only, never as a business result.
- Every response carries
X-Request-ID(32 lowercase hex characters), generated by the platform. Provide this value when reporting a problem.
Notification and review signature
Notification request example:
POST <callback URL provided by the merchant>
Content-Type: application/json
X-Cbc-Timestamp: 1792382460
X-Cbc-Nonce: 9f2c4e6a8b0d1f3e5a7c9e1b3d5f7a9c
X-Cbc-Sign-Alg: RSA-SHA256
X-Cbc-Signature: <base64>
{"data":{ ...fields of each notification... }}
Result notifications, the withdrawal order 2nd review and the exchange order 2nd review sent by the platform use the body {"data":{...}} and carry the signature in 4 headers:
| Header | Description |
|---|---|
| X-Cbc-Timestamp | Unix timestamp in seconds |
| X-Cbc-Nonce | Random string, 32 lowercase hex characters |
| X-Cbc-Sign-Alg | Always RSA-SHA256 |
| X-Cbc-Signature | Signature of the canonical string, standard Base64 |
The canonical string is the same as for responses, 4 lines: timestamp, nonce, RSA-SHA256, and the lowercase hex SHA-256 of the raw request body bytes.
Receiver verification steps:
- All 4 headers are present and
X-Cbc-Sign-AlgisRSA-SHA256; X-Cbc-Timestampis within 300 seconds of the current time;- Verify the signature with the platform public key (the platform risk control public key for the withdrawal and exchange reviews), hashing the raw body bytes exactly as received;
- The nonce has not been seen within 300 seconds (caching it for 660 seconds is recommended);
- Only after all of the above pass, parse the body, process it and reply.
- The platform generates a new timestamp, nonce and signature for every send, including retries.
- The success reply to a result notification is the same as in v1; see each notification.
- The signature version is configured by the platform per merchant; see Migrating from v1 to v2.
Self-check with the fixture
Test public key (for integration testing only, never for production):
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqiuoVcSN40UbFXjL7pT5
qbTE8xF7aQPCXhcytN8vqtHjDxd0Zjpx1oIkX456njAG68LxWCGba6LPxY+U7hGs
pCJju3iDivZyTncXz5xNm2H18PoEFSuV1IGredG5yetyChZFaNXoihdHN2hnMRvu
yPAT8U/buy+pI9AqH3J+W+Td9gZnswj1O3zQeerwj9q0CJCKXsRm+eBMb6h5z+yM
6GkXbNq4IFTiEUQMZYG+NxTRMrjLCZFLpu3C7spPdgXUOmuu2S3L6TxMq6BD8umm
OF9vvNV2GEmO4JFlJ6aYBiT0yPZ6K7wfCFgLbWuqYBk/1JKKoJx8eX7sJFypJLmW
sQIDAQAB
-----END PUBLIC KEY-----
Request with path
/v2/balance(empty base_path) and body{"coin":"btc"}, canonical string and signature:
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==
Response / notification with body
{"data":{"order_id":"1","amount":"1.5"}}, canonical string and signature:
1785340800
abcdef0123456789
RSA-SHA256
631af6d41ca0da36316c0d6ad0df8e338c23a9878548d5ee6831df183e70e25e
gcvD6paex+8LZZdtsuZ/251TzIIrDFChucvsUWj2V+Ls6f8uwgS7WJvQxBqx+b7n4eEBwyt/oYVxxBHk1K88v3wIweyrv+dqc3e7iHDlWJNFZE8oRsjGZCEzbBr0Trc9bqJwCqMiK0uosV9xcOVy6eDbqx7l8NDYaKz/9rWpD5aF/xhgQiCSO4WzhFenkWk0cnXwLX+gFU6NM2c3hmNDvY+QexWyxLYri/PYpXhFpDt/ethCtmXSyXuhu2iIef7Ijb1u3pApe2s9Ghx2P33TIY/+YDATjv5+nhhdRJYflL99odVHQA+pYwo8oIRibsTDdyadoV7D0d4Ly8uQ0OUYhQ==
On the right are a 2048-bit test public key and a fixed request and response canonical string with their signatures. When integrating:
- Build the canonical string from the request example fields; it must match the one on the right byte for byte;
- Verify both signatures on the right with the test public key; both must pass (skip the 300-second window when verifying the response).
If both checks pass, your canonical string, SHA-256 digest and RSA implementation match the platform. This key is for integration testing only and must never be used in production.
Client examples
// Go 1.18+, standard library only
//
// Calling an API:
// client, err := cbc.NewClient("<baseUrl>", "hxgmau9imt86qky9", "admin", merchantPrivateKeyPEM, platformPublicKeyPEM)
// resp, err := client.Post("/v2/balance", map[string]any{"coin": "btc"})
//
// Receiving a notification (net/http):
// body, _ := io.ReadAll(r.Body)
// if err := cbc.VerifyBody(r.Header, body, client.PlatformKey, true); err != nil { /* reject */ }
// // de-duplicate by X-Cbc-Nonce, then parse 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 calls CipherBC API v2: signs requests and verifies responses with the platform public key.
type Client struct {
BaseURL string // baseUrl provided by the platform
AppID string
KeyVersion string // defaults to admin
PrivateKey *rsa.PrivateKey // merchant private key (PKCS#8)
PlatformKey *rsa.PublicKey // platform public key (PKIX)
HTTP *http.Client
basePath string // path part of 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 sends a request. Returns the verified response body.
// path is the API path, e.g. /v2/balance; params are the business parameters.
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()
// The canonical string uses the full request path: 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
}
// Send exactly the bytes that were signed
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") == "" {
// Requests rejected before verification (e.g. 601-606) get unsigned responses; use the body for troubleshooting only
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 returns the request canonical string: 7 lines joined by \n, no trailing newline.
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 returns the canonical string for responses, notifications and reviews: 4 lines joined by \n, no trailing newline.
func BodyCanonical(timestamp, nonce string, body []byte) string {
return strings.Join([]string{timestamp, nonce, SignAlg, Sha256Hex(body)}, "\n")
}
// VerifyBody verifies the 4 signature headers of a response, notification or review request.
// Set checkTime to true to also enforce the 300-second window (when receiving notifications and review requests).
// After it passes, de-duplicate by X-Cbc-Nonce before parsing the 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 signs an outgoing body and returns the 4 signature headers (e.g. the withdrawal review response).
// Send the body unchanged after signing; do not re-serialize it.
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 returns 32 lowercase hex characters
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
// Calling an API:
// $client = new CbcClient('<baseUrl>', 'hxgmau9imt86qky9', 'admin', $merchantPrivateKeyPem, $platformPublicKeyPem);
// $resp = $client->post('/v2/balance', ['coin' => 'btc']);
//
// Receiving a notification:
// $body = file_get_contents('php://input');
// $headers = array_change_key_case(getallheaders(), CASE_LOWER);
// CbcClient::verifyBody($headers, $body, $platformPublicKeyPem, true); // throws on failure
// // de-duplicate by X-Cbc-Nonce, then json_decode($body, true)
// PHP 7.4+, requires the openssl and curl extensions
class CbcClient
{
const SIGN_ALG = 'RSA-SHA256';
const TIME_WINDOW = 300; // seconds
private $baseUrl;
private $basePath; // path part of $baseUrl (base_path)
private $appId;
private $keyVersion;
private $privateKey; // merchant private key (PKCS#8 PEM)
private $platformKey; // platform public key (PKIX PEM)
// $baseUrl is provided by the platform
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 is the API path, e.g. /v2/balance; $params are the business parameters. Returns the verified response as an array.
public function post($path, array $params = [])
{
// Send {} rather than [] when there are no parameters
$body = empty($params) ? '{}' : json_encode($params, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
$timestamp = (string)time();
$nonce = self::newNonce();
// The canonical string uses the full request path: 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, // Send exactly the bytes that were signed
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'])) {
// Requests rejected before verification (e.g. 601-606) get unsigned responses; use the body for troubleshooting only
$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);
}
// Request canonical string: 7 lines joined by \n, no trailing newline
public static function requestCanonical($method, $path, $appId, $keyVersion, $timestamp, $nonce, $body)
{
return implode("\n", [$method, $path, $appId, $keyVersion, $timestamp, $nonce, hash('sha256', $body)]);
}
// Canonical string for responses, notifications and reviews: 4 lines joined by \n, no trailing newline
public static function bodyCanonical($timestamp, $nonce, $body)
{
return implode("\n", [$timestamp, $nonce, self::SIGN_ALG, hash('sha256', $body)]);
}
// Verifies the 4 signature headers of a response, notification or review request; throws on failure.
// $headers keys are lowercase header names; set $checkTime to true to also enforce the 300-second window (when receiving notifications and review requests).
// After it passes, de-duplicate by X-Cbc-Nonce before parsing the 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');
}
}
// Signs an outgoing body and returns the 4 signature headers (e.g. the withdrawal review response). Send the body unchanged after signing.
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 lowercase hex characters
public static function newNonce()
{
return bin2hex(random_bytes(16));
}
}
// Calling an API:
// const client = new CbcClient('<baseUrl>', 'hxgmau9imt86qky9', 'admin', merchantPrivateKeyPem, platformPublicKeyPem);
// const resp = await client.post('/v2/balance', { coin: 'btc' });
//
// Receiving a notification (Express; use express.raw({ type: 'application/json' }) to keep the raw body):
// verifyBody((name) => req.get(name), req.body, platformPublicKeyPem, true); // throws on failure
// // de-duplicate by X-Cbc-Nonce, then JSON.parse(req.body)
// Node.js 18+
import crypto from 'node:crypto';
export const SIGN_ALG = 'RSA-SHA256';
export const TIME_WINDOW = 300; // seconds
export const sha256Hex = (buf) => crypto.createHash('sha256').update(buf).digest('hex');
export const newNonce = () => crypto.randomBytes(16).toString('hex'); // 32 lowercase hex characters
// Request canonical string: 7 lines joined by \n, no trailing newline
export function requestCanonical(method, path, appId, keyVersion, timestamp, nonce, body) {
return [method, path, appId, keyVersion, timestamp, nonce, sha256Hex(body)].join('\n');
}
// Canonical string for responses, notifications and reviews: 4 lines joined by \n, no trailing newline
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'));
}
// Verifies the 4 signature headers of a response, notification or review request; throws on failure.
// getHeader(name) returns a header value; set checkTime to true to also enforce the 300-second window (when receiving notifications and review requests).
// After it passes, de-duplicate by X-Cbc-Nonce before parsing the 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');
}
}
// Signs an outgoing body and returns the 4 signature headers (e.g. the withdrawal review response). Send the body unchanged after signing.
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 provided by the platform; merchantPrivateKey is PKCS#8 PEM, platformPublicKey is PKIX PEM
constructor(baseUrl, appId, keyVersion, merchantPrivateKey, platformPublicKey) {
this.baseUrl = baseUrl.replace(/\/+$/, '');
this.basePath = new URL(this.baseUrl).pathname.replace(/\/+$/, ''); // path part of baseUrl (base_path)
this.appId = appId;
this.keyVersion = keyVersion || 'admin';
this.privateKey = merchantPrivateKey;
this.platformKey = platformPublicKey;
}
// path is the API path, e.g. /v2/balance; params are the business parameters. Returns the verified response JSON.
async post(path, params = {}) {
const body = Buffer.from(JSON.stringify(params));
const timestamp = String(Math.floor(Date.now() / 1000));
const nonce = newNonce();
// The canonical string uses the full request path: base_path + path
const canonical = requestCanonical('POST', this.basePath + path, this.appId, this.keyVersion, timestamp, nonce, body);
// Send exactly the bytes that were signed
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')) {
// Requests rejected before verification (e.g. 601-606) get unsigned responses; use the body for troubleshooting only
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'));
}
}
// Calling an API:
// CbcClient client = new CbcClient("<baseUrl>", "hxgmau9imt86qky9", "admin", merchantPrivateKeyPem, platformPublicKeyPem);
// String resp = client.post("/v2/balance", Map.of("coin", "btc"));
//
// Receiving a notification: read the raw body bytes, put the 4 signature headers into a Map, then call
// CbcClient.verifyBody(headers, rawBody, CbcClient.parsePublicKey(platformPublicKeyPem), true); // throws on failure
// // de-duplicate by X-Cbc-Nonce, then parse the body
// Java 11+, no third-party dependencies
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; // seconds
private static final SecureRandom RANDOM = new SecureRandom();
private final String baseUrl;
private final String basePath; // path part of baseUrl (base_path)
private final String appId;
private final String keyVersion;
private final PrivateKey privateKey; // merchant private key (PKCS#8)
private final PublicKey platformKey; // platform public key (PKIX)
private final HttpClient http = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(10)).build();
// baseUrl is provided by the platform
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 is the API path, e.g. /v2/balance; params are the business parameters, with String, Number, Boolean, Map or List values.
// Returns the verified response body.
public String post(String path, Map<String, ?> params) throws Exception {
return post(path, toJson(params));
}
// path is the API path, e.g. /v2/balance; jsonBody is the business parameters as JSON, "{}" when there are none.
// Returns the verified response 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();
// The canonical string uses the full request path: base_path + path
String canonical = requestCanonical("POST", basePath + path, appId, keyVersion, timestamp, nonce, body);
// Send exactly the bytes that were signed
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()) {
// Requests rejected before verification (e.g. 601-606) get unsigned responses; use the body for troubleshooting only
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;
}
// Request canonical string: 7 lines joined by \n, no trailing newline
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));
}
// Canonical string for responses, notifications and reviews: 4 lines joined by \n, no trailing newline
public static String bodyCanonical(String timestamp, String nonce, byte[] body) throws Exception {
return String.join("\n", timestamp, nonce, SIGN_ALG, sha256Hex(body));
}
// Verifies the 4 signature headers of a response, notification or review request; throws on failure.
// headers keys are header names such as X-Cbc-Timestamp; set checkTime to true to also enforce the 300-second window (when receiving notifications and review requests).
// After it passes, de-duplicate by X-Cbc-Nonce before parsing the 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");
}
}
// Signs an outgoing body and returns the 4 signature headers (e.g. the withdrawal review response). Send the body unchanged after signing.
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 lowercase hex characters
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)));
}
// Minimal JSON serializer; replace it with Jackson or Gson if your project already uses one
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();
}
}
A complete client is provided for each of go, php, js and java, all verified against the fixture above:
Post/post: signs the request, sends it, verifies the response and returns the verified response body;VerifyBody/verifyBody: verifies the 4 signature headers of a response, result notification or review request; enable the 300-second window check when receiving notifications;SignBody/signBody: signs an outgoing body, used for the withdrawal and exchange review responses.
The examples of every API call these clients and show only the path and business parameters.
Key requirements
- RSA keys must be at least 2048 bits.
- Public keys use PKIX (
-----BEGIN PUBLIC KEY-----); private keys use PKCS#8 (-----BEGIN PRIVATE KEY-----). - The merchant generates two key pairs, one for business and one for risk control. They must not be shared:
| Key pair | Usage | Provided by the platform |
|---|---|---|
| Business key pair | The merchant private key signs all API requests; the merchant public key lets the platform verify requests | Platform public key, to verify responses and result notifications |
| Risk control key pair | The merchant risk control private key signs the responses of the withdrawal and exchange 2nd reviews; the merchant risk control public key lets the platform verify review responses | Platform risk control public key, to verify withdrawal and exchange 2nd review requests |
Key generation commands
mkdir rsa_pem && cd rsa_pem
# business key pair
# generate private key
openssl genrsa -out app_private_key.pem 2048
# convert private key to PKCS#8 format
openssl pkcs8 -topk8 -inform PEM -in app_private_key.pem -outform PEM -nocrypt -out app_private_key_pkcs8.pem
# generate public key from private key
openssl rsa -in app_private_key.pem -pubout -out app_public_key.pem
# risk control key pair
# generate private key
openssl genrsa -out risk_private_key.pem 2048
# convert private key to PKCS#8 format
openssl pkcs8 -topk8 -inform PEM -in risk_private_key.pem -outform PEM -nocrypt -out risk_private_key_pkcs8.pem
# generate public key from private key
openssl rsa -in risk_private_key.pem -pubout -out risk_public_key.pem
Run the OpenSSL commands below one by one in a terminal on your own computer to generate the business and risk control 2048-bit key pairs. No coding is needed. macOS and Linux usually ship with OpenSSL; on Windows, run them in Git Bash. The same commands are on the right for copying.
- Create and enter a directory:
mkdir rsa_pem && cd rsa_pem - Generate the business key pair:
- Generate private key:
openssl genrsa -out app_private_key.pem 2048 - Convert private key to PKCS#8 format:
openssl pkcs8 -topk8 -inform PEM -in app_private_key.pem -outform PEM -nocrypt -out app_private_key_pkcs8.pem - Generate public key from private key:
openssl rsa -in app_private_key.pem -pubout -out app_public_key.pem
- Generate private key:
- Generate the risk control key pair:
- Generate private key:
openssl genrsa -out risk_private_key.pem 2048 - Convert private key to PKCS#8 format:
openssl pkcs8 -topk8 -inform PEM -in risk_private_key.pem -outform PEM -nocrypt -out risk_private_key_pkcs8.pem - Generate public key from private key:
openssl rsa -in risk_private_key.pem -pubout -out risk_public_key.pem
- Generate private key:
When done, the rsa_pem directory contains these files to use:
| File | Description |
|---|---|
app_private_key_pkcs8.pem |
Merchant business private key (PKCS#8). Configure it in the client to sign requests |
app_public_key.pem |
Merchant business public key. Give it to the platform |
risk_private_key_pkcs8.pem |
Merchant risk control private key (PKCS#8). Configure it in the withdrawal and exchange review endpoints to sign review responses |
risk_public_key.pem |
Merchant risk control public key. Give it to the platform |
Keep both private keys safe and never share them with anyone. When giving the two public keys to the platform, state which is the business key and which is the risk control key.
Public information description
The following information is common to all interfaces, and the description of each interface is not repeated
API address
Request URL = baseUrl + API path. Please contact customer service to obtain the baseUrl; v1 and v2 share the same baseUrl. API paths in this documentation (such as /v2/balance) are relative to baseUrl. The path part of baseUrl after the host is called base_path; the canonical string uses the full request path <base_path>/v2/....
Production Environment
Please contact customer service to obtain the API address
test environment
Please contact customer service to obtain the API address
Common request headers
| Header | Required | Case | Description |
|---|---|---|---|
| X-Cbc-App-Id | Yes | hxgmau9imt86qky9 | Merchant ID assigned by the system when docking |
| X-Cbc-Key-Version | No | admin | key version number: admin / read / arbitrary - can be authorized for any 1-n interfaces; defaults to admin |
| X-Cbc-Timestamp | Yes | 1792382460 | Unix timestamp in seconds, ignoring time zone |
| X-Cbc-Nonce | Yes | 7c1e9a3b5d7f9b1d3f5a7c9e1b3d5f7a | Random string of 16–64 characters, unique per request |
| X-Cbc-Sign-Alg | Yes | RSA-SHA256 | Signature algorithm, fixed value |
| X-Cbc-Signature | Yes | Dr7MnhPYh… | Signature, see Signature Regulations |
Response headers
| Header | Description |
|---|---|
| X-Request-ID | Request ID, 32 lowercase hex characters, generated by the platform. Provide it when reporting a problem |
| X-Cbc-Timestamp | Response signature timestamp |
| X-Cbc-Nonce | Response signature nonce |
| X-Cbc-Sign-Alg | Always RSA-SHA256 |
| X-Cbc-Signature | Response signature. Responses that fail during signature verification carry no signature headers |
Common response parameters
| Parameter | Type | Description |
|---|---|---|
| status | integer | Status code; 200 means success, see Response status code |
| msg | string | Status description |
| data | object | Business data; null when there is none |
| date_time | string | Server time in Beijing time, format YYYY-MM-DD HH:mm:ss |
| time_stamp | integer | Unix timestamp in seconds |
Public Information Notice
| Name | Type | Case | Description |
|---|---|---|---|
| time1 | timeStamp | 1578829811 | UTC time unified time without time zone |
| Time 2 | DateTime | 2020-01-09 15:48:42 | The global system defaults to Beijing time if this format appears |
| Request Method | POST | — | All requests are POST |
| Encoding | UTF-8 | — | Other encodings may produce garbled characters and errors |
| Communication Protocol | HTTPS | https | Currently only HTTPS is supported |
| Signature Type | RSA-SHA256 | Dr7MnhPYh… | RSA keys of at least 2048 bits, see Signature Regulations |
| Request and Return | JSON | — | All request and response parameters are in JSON format |
| Note on the amount parameter | string | — | The number of digits after the decimal point exceeds 8, and the number of digits before the decimal point exceeds 12, which cannot be passed, and the last invalid 0 must be deleted. |
API list
The table below lists the APIs and paths of each section. Paths are relative to baseUrl.
| Section | API | Path |
|---|---|---|
| Address | Address get | /v2/address/getBatch |
| Address | Address list | /v2/address/list |
| Address | eos-like address + memo mode | /v2/address/coinAccount |
| Address | Address state synchronization | /v2/address/syncStatus |
| Address | Address status batch synchronization | /v2/address/syncBatchStatus |
| Address | Address verification | /v2/address/verifyAddress |
| Address | Address AML verification | /v2/address/verifyAml |
| Deposit | Top-up list | /v2/receive/list |
| Deposit | Account balance query | /v2/balance |
| Deposit | Deposit result callback notification | Callback URL provided by the merchant |
| Withdraw | Withdrawal application | /v2/transfer |
| Withdraw | Withdrawal list | /v2/transfer/list |
| Withdraw | Withdrawal result callback notification | Callback URL provided by the merchant |
| Exchange | Redemption application | /v2/exchange/index |
| Exchange | Exchange account recharge | /v2/exchange/transfer |
| Exchange | Exchange rate | /v2/rate/exchange |
| Exchange | Batch query exchange rate | /v2/rate/exchangeBatch |
| Exchange | Exchange balance query | /v2/balance/exchange |
| Exchange | Exchange transaction pair query | /v2/exchange/coin |
| Exchange | Exchange list query | /v2/exchange/list |
| Exchange | Redeem callback notification | Callback URL provided by the merchant |
| Statistics | Merchant financial settlement ledger | /v2/balance/generalAccount |
| Statistics | Merchant deposit/withdrawal successful number | /v2/statistics/transfer |
| Risk control callback | The second review of the withdrawal order | Review URL provided by the merchant |
| Risk control callback | 2nd review for exchange order | Review URL provided by the merchant |
| Risk control callback | MPC order review API | Review URL provided by the merchant |
| Risk control callback | CoSigner-MPC order review API | Review URL provided by the merchant |
| H5 Deposit | Create Order | /v2/h5Order/create |
| H5 Deposit | Cancel Order | /v2/h5Order/cancel |
| H5 Deposit | Order Details | /v2/h5Order/detail |
| H5 Deposit | H5 Deposit result callback notification | Callback URL provided by the merchant |
| Outer Address Monitoring | Add Outer Address | /v2/outerAddress/add |
| Outer Address Monitoring | Delete Outer Address | /v2/outerAddress/delete |
| Outer Address Monitoring | Outer Address Transaction Notify | Callback URL provided by the merchant |
| Other | Coin query | /v2/coin/list |
| Other | Coin exchange rate | /v2/rate/index |
| Other | Coin to fiat currency rate | /v2/rate/fiatCurrency |
| Other | Collection fee calculation | /v2/balance/transactionFee |
| Other | Withdrawal gas fee estimate query | /v2/transfer/transactionFee |
| Other | Refund order list | /v2/refund/list |
| Other | Check whether the number of currencies recorded in its ledger is consistent with the data in its on-chain wallet | /v2/reconcile/balances |
| Other | Check whether the number of coins in an account address is consistent with the number on the chain | /v2/reconcile/addressBalance |
| Other | Check whether the withdrawal data recorded in the internal ledger is consistent with the data on its wallet chain | /v2/reconcile/withdrawal |
- The version of platform messages (result notifications and reviews) depends on the merchant's signature version; see the next section. The MPC order review and the CoSigner-MPC order review are still v1; for the signing rules see the v1 documentation.
Migrating from v1 to v2
Differences
| Item | v1 | v2 |
|---|---|---|
| Path | /... |
/v2/...; 4 path groups change to lower camelCase, see below |
| Request signature | app_id, version, time, key_version, sign in the body |
6 headers: X-Cbc-App-Id, X-Cbc-Key-Version, X-Cbc-Timestamp, X-Cbc-Nonce, X-Cbc-Sign-Alg, X-Cbc-Signature |
| Request canonical string | Sorted and joined parameters, MD5 digest | 7 lines: method, path, app_id, key_version, timestamp, nonce, body SHA-256 |
| Response | sign in the body |
4 response headers; canonical string of 4 lines: timestamp, nonce, RSA-SHA256, body SHA-256 |
| Result notifications, withdrawal and exchange reviews | sign in the body |
Body is {"data":{...}}; signature in 4 headers |
Path changes
| 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 |
All other APIs only add /v2 in front of the path, e.g. /address/getBatch → /v2/address/getBatch. v1 and v2 share the same baseUrl.
Migration steps
- Requests: migrate at any time without notifying the platform. v2 requests do not depend on the merchant's signature version and use the same merchant key, so you can switch API by API. The key must meet the key requirements; replace keys shorter than 2048 bits first.
- Result notifications and reviews: switched together by the platform through the merchant's signature version. With v2, the deposit (received and confirmed), withdrawal, exchange, H5 order and outer address transaction notifications, as well as the withdrawal order 2nd review and the exchange order 2nd review, all switch to v2; the MPC order review and the CoSigner-MPC order review stay on v1.
- Ask the platform to switch the signature version only after your notification receivers, your withdrawal review endpoint and your exchange review endpoint (if exchange is enabled) are all upgraded. To roll back, all three return to v1 together.
- During the switch, accept both formats and reply in the format of the request: handle it as v2 if the request carries the
X-Cbc-Signatureheader, otherwise as v1 (signin the body). The platform chooses the format by the merchant's version at each send; pending notifications and retries use the new format from the next send.