Outer Address Monitoring
Add Outer Address
Request example:
POST <base_path>/v2/outerAddress/add 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>
{"chain":"bnb_bsc","addresses":["0xeb482aee7b329058ec81223f98488d28e12b15a2","0x4d5fa5df5963405d5ecc40ea25c08fbed129004f"]}
resp, err := client.Post("/v2/outerAddress/add", map[string]any{
"chain": "bnb_bsc",
"addresses": []string{"0xeb482aee7b329058ec81223f98488d28e12b15a2", "0x4d5fa5df5963405d5ecc40ea25c08fbed129004f"},
})
$resp = $client->post('/v2/outerAddress/add', [
'chain' => 'bnb_bsc',
'addresses' => ['0xeb482aee7b329058ec81223f98488d28e12b15a2', '0x4d5fa5df5963405d5ecc40ea25c08fbed129004f'],
]);
const resp = await client.post('/v2/outerAddress/add', {
chain: 'bnb_bsc',
addresses: ['0xeb482aee7b329058ec81223f98488d28e12b15a2', '0x4d5fa5df5963405d5ecc40ea25c08fbed129004f'],
});
String resp = client.post("/v2/outerAddress/add", Map.of(
"chain", "bnb_bsc",
"addresses", List.of("0xeb482aee7b329058ec81223f98488d28e12b15a2", "0x4d5fa5df5963405d5ecc40ea25c08fbed129004f")));
Example of return result:
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": {
"fail_addresses": []
},
"date_time": "2022-10-11 16:59:35",
"time_stamp": 1665478775
}
- merchant submit addresses for monitoring transaction
HTTP Request
POST /v2/outerAddress/add
Request parameter description
For the common headers see Signature Regulations; the table below lists only the business parameters in the body.
| Parameter | Required | Type | Description |
|---|---|---|---|
| chain | Yes | string | the chain name, 12 character limit |
| addresses | Yes | array | addresses, array length limit 100 |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| status | integer | status code |
| msg | string | status description |
| data | object | response data. |
| data.fail_addresses | array | save fail addresses, empty when no fail |
| date_time | string | formated time |
| time_stamp | integer | timestamp in seconds |
Delete Outer Address
Request example:
POST <base_path>/v2/outerAddress/delete 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>
{"chain":"bnb_bsc","addresses":["0xeb482aee7b329058ec81223f98488d28e12b15a2","0x4d5fa5df5963405d5ecc40ea25c08fbed129004f"]}
resp, err := client.Post("/v2/outerAddress/delete", map[string]any{
"chain": "bnb_bsc",
"addresses": []string{"0xeb482aee7b329058ec81223f98488d28e12b15a2", "0x4d5fa5df5963405d5ecc40ea25c08fbed129004f"},
})
$resp = $client->post('/v2/outerAddress/delete', [
'chain' => 'bnb_bsc',
'addresses' => ['0xeb482aee7b329058ec81223f98488d28e12b15a2', '0x4d5fa5df5963405d5ecc40ea25c08fbed129004f'],
]);
const resp = await client.post('/v2/outerAddress/delete', {
chain: 'bnb_bsc',
addresses: ['0xeb482aee7b329058ec81223f98488d28e12b15a2', '0x4d5fa5df5963405d5ecc40ea25c08fbed129004f'],
});
String resp = client.post("/v2/outerAddress/delete", Map.of(
"chain", "bnb_bsc",
"addresses", List.of("0xeb482aee7b329058ec81223f98488d28e12b15a2", "0x4d5fa5df5963405d5ecc40ea25c08fbed129004f")));
Example of return result:
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": [],
"date_time": "2022-10-11 16:59:35",
"time_stamp": 1665478775
}
- merchant remove addresses under monitoring
HTTP Request
POST /v2/outerAddress/delete
Request parameter description
For the common headers see Signature Regulations; the table below lists only the business parameters in the body.
| Parameter | Required | Type | Description |
|---|---|---|---|
| chain | Yes | string | the chain name, 12 character limit |
| addresses | Yes | array | addresses, array length limit 100 |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| status | integer | status code |
| msg | string | status description |
| data | object | response data |
| date_time | string | formated time |
| time_stamp | integer | timestamp in seconds |
Outer Address Transaction Notify
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": {
"address": "0xeb482aee7b329058ec81223f98488d28e12b15a2",
"amount": "0.00013556",
"chain": "bnb_bsc",
"coin": "bnb_bsc",
"confirm_count": 12,
"gas_fee": "0.000105",
"status": 1,
"time": 1665479732,
"token_address": "",
"transaction_type": 2,
"txid": "0x735dc8becd0d5dc0023b526584b75c8772551fc9268668991608dadc69facb39"
}
}
http.HandleFunc("/notify/outer-address", func(w http.ResponseWriter, r *http.Request) {
body, _ := io.ReadAll(r.Body)
if err := cbc.VerifyBody(r.Header, body, client.PlatformKey, true); err != nil {
http.Error(w, "invalid signature", http.StatusUnauthorized)
return
}
// Signature verified: de-duplicate by X-Cbc-Nonce, then parse the body and handle data
w.Header().Set("Content-Type", "application/json")
w.Write([]byte(`{"status":200,"msg":"success","data":{"success_data":"success"}}`))
})
$body = file_get_contents('php://input');
$headers = array_change_key_case(getallheaders(), CASE_LOWER);
try {
CbcClient::verifyBody($headers, $body, $platformPublicKeyPem, true);
} catch (RuntimeException $e) {
http_response_code(401);
exit;
}
// Signature verified: de-duplicate by X-Cbc-Nonce, then parse the body and handle data
$notify = json_decode($body, true);
header('Content-Type: application/json');
echo '{"status":200,"msg":"success","data":{"success_data":"success"}}';
app.post('/notify/outer-address', express.raw({ type: 'application/json' }), (req, res) => {
try {
verifyBody((name) => req.get(name), req.body, platformPublicKeyPem, true);
} catch (e) {
return res.status(401).end();
}
// Signature verified: de-duplicate by X-Cbc-Nonce, then parse the body and handle data
const notify = JSON.parse(req.body);
res.type('application/json').send('{"status":200,"msg":"success","data":{"success_data":"success"}}');
});
@PostMapping(value = "/notify/outer-address", produces = "application/json")
public ResponseEntity<String> notify(@RequestHeader HttpHeaders headers, @RequestBody byte[] body) {
Map<String, String> sig = new HashMap<>();
for (String name : new String[]{"X-Cbc-Timestamp", "X-Cbc-Nonce", "X-Cbc-Sign-Alg", "X-Cbc-Signature"}) {
sig.put(name, headers.getFirst(name));
}
try {
CbcClient.verifyBody(sig, body, platformKey, true);
} catch (Exception e) {
return ResponseEntity.status(401).build();
}
// Signature verified: de-duplicate by X-Cbc-Nonce, then parse the body and handle data
return ResponseEntity.ok("{\"status\":200,\"msg\":\"success\",\"data\":{\"success_data\":\"success\"}}");
}
Merchant reply example:
{
"status": 200,
"msg": "success",
"data": {
"success_data": "success"
}
}
- when trasaction of monitoring address commited on chain, platform will request this API, and merchant response to it
- if merchant response is fail or incorrect, platform will retry, until got success or 1 hour timeout. Retry at, 30 second, 1 minute, 3 minute, 7 minute, 15 minute, 25 minute, 40 minute, 60 minute, after the first fail.
HTTP Request
POST: The specific callback address is provided by the merchant to the platform side
Request parameter description
For the request headers and the receiver verification steps see Notification and review signature. Verify the signature with the platform public key before parsing the body; the table below lists the fields in the body.
| Parameter | Required | Type | Description |
|---|---|---|---|
| data | Yes | object | transaction object |
| data.address | Yes | string | merchant monitoring address |
| data.amount | Yes | string | amount |
| data.chain | Yes | string | chain symbol |
| data.coin | Yes | string | contract coin symbol, main coin same to chain |
| data.confirm_count | Yes | integer | confirmations count |
| data.gas_fee | Yes | string | gas fee |
| data.status | Yes | integer | status: 0=unconfirm, 1=confirmed, 2=abnormal |
| data.status_msg | No | string | failure reason, sent when status=2 |
| data.time | Yes | integer | block time (second) |
| data.token_address | No | string | contract token address, main coin is empty |
| data.transaction_type | Yes | integer | transaction type: 1=transfer in, 2=transfer out |
| data.txid | Yes | string | transaction hash |
Response Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| status | Yes | integer | status code, 200 is ok |
| msg | Yes | string | status code description |
| data | Yes | object | response data |
| data.success_data | Yes | string | whether handle success, if not return 'success', platform will retry request |