NAV
go php js java

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

Coin Name Full name Blockchain Explorer
btc btc https://blockchair.com/bitcoin
eth eth https://etherscan.io
bnb_bsc BSC(BNB Smart Chain) https://bscscan.com
qtum qtum https://explorer.qtum.org
trx Tron https://tronscan.io
a Vaulta(Upgraded from the EOS) https://vaultascan.io/
xrp xrp https://xrpscan.com
doge doge https://dogechain.info
ltc ltc https://litecoinblockexplorer.net
dash dash https://dashblockexplorer.com
dcr dcr https://dcrdata.decred.org
bch Bitcoin Cash https://blockchair.com/bitcoin-cash
fil fil https://filscan.io
sol solana https://explorer.solana.com
pol Polygon https://polygonscan.com
avax_c avax c chain https://snowtrace.io
avax_x X chain of avax https://explorer-xp.avax.network
lunc lunc https://finder.terra.money/classic
bsv Bitcoin SV https://www.bitcoinsv.io
atom atom https://www.mintscan.io/injective
eth_optimism optimism https://optimistic.etherscan.io
eth_arbitrum arbitrum https://arbiscan.io
ada cardano https://cardanoscan.io
core core https://scan.coredao.org
eth_zksync ZKsync Era https://explorer.zksync.io
algo Algorand https://algoexplorer.io
sui Sui https://suiexplorer.com
eth_base Base https://basescan.org
ton Toncoin https://tonviewer.com
smart smart https://smartexplorer.com
tfuel_theta TFuel on Theta https://www.thetascan.io
kas Kaspa https://explorer.kaspa.org
assethub_dot AssetHub Polkadot https://assethub-polkadot.subscan.io
apt aptos https://explorer.aptoslabs.com
dag dag https://mainnet.dagexplorer.io
eth_deriw Deriw https://explorer.deriw.com/
hype Hyperliquid https://app.hyperliquid.xyz/explorer
main_bnb opBNB https://opbnbscan.com/
mnt Mantle https://mantlescan.xyz/
s Sonic https://sonicscan.org/

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.

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:

  1. HTTP method, always POST;
  2. 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/balance becomes <base_path>/v2/balance;
  3. Value of X-Cbc-App-Id;
  4. Value of X-Cbc-Key-Version, admin when omitted;
  5. Value of X-Cbc-Timestamp;
  6. Value of X-Cbc-Nonce;
  7. Lowercase hex SHA-256 of the raw request body bytes.

Signature = Base64(RSA_PKCS1v15_Sign(merchant private key, SHA-256, canonical string)).

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.

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:

  1. All 4 headers are present and X-Cbc-Sign-Alg is RSA-SHA256;
  2. X-Cbc-Timestamp is within 300 seconds of the current time;
  3. 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;
  4. The nonce has not been seen within 300 seconds (caching it for 660 seconds is recommended);
  5. Only after all of the above pass, parse the body, process it and reply.

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:

  1. Build the canonical string from the request example fields; it must match the one on the right byte for byte;
  2. 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:

The examples of every API call these clients and show only the path and business parameters.

Key requirements

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.

  1. Create and enter a directory: mkdir rsa_pem && cd rsa_pem
  2. 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
  3. 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

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

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

  1. 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.
  2. 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.
  3. 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.
  4. 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-Signature header, otherwise as v1 (sign in 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.