外部地址
新增外部地址
请求示例:
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")));
返回结果示例:
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": "请求成功",
"data": {
"fail_addresses": []
},
"date_time": "2022-10-11 16:59:35",
"time_stamp": 1665478775
}
- 商户提交想要监控交易的地址到平台
HTTP Request
POST /v2/outerAddress/add
请求参数
公共 Header 见签名规则,下表只列 body 中的业务参数。
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| chain | 是 | string | 12个字符以内,地址所属主链 |
| addresses | 是 | array | 地址,数组长度限制不超过100个 |
返回参数说明
| 参数名 | 类型 | 说明 |
|---|---|---|
| status | integer | 状态码 |
| msg | string | 状态描述 |
| data | object | 具体见下面 “data细节说明”。 |
| data.fail_addresses | array | 保存出错的地址,全部保存成功则该值为空 |
| date_time | string | 响应时间 |
| time_stamp | integer | 响应时间单位秒 |
删除外部地址
请求示例:
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")));
返回结果示例:
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": "请求成功",
"data": [],
"date_time": "2022-10-11 16:59:35",
"time_stamp": 1665478775
}
- 删除已加入交易监控的地址
HTTP Request
POST /v2/outerAddress/delete
请求参数
公共 Header 见签名规则,下表只列 body 中的业务参数。
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| chain | 是 | string | 12个字符以内,地址所属主链 |
| addresses | 是 | array | 地址,数组长度限制不超过100个 |
返回参数说明
| 参数名 | 类型 | 说明 |
|---|---|---|
| status | integer | 状态码 |
| msg | string | 状态描述 |
| data | object | 无具体数据,返回空 |
| date_time | string | 响应时间 |
| time_stamp | integer | 响应时间单位秒 |
外部地址交易变动回调通知
回调请求示例:
POST <商户提供的回调地址>
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
}
// 验签已通过:按 X-Cbc-Nonce 去重后再解析 body,处理 data
w.Header().Set("Content-Type", "application/json")
w.Write([]byte(`{"status":200,"msg":"请求成功","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;
}
// 验签已通过:按 X-Cbc-Nonce 去重后再解析 body,处理 data
$notify = json_decode($body, true);
header('Content-Type: application/json');
echo '{"status":200,"msg":"请求成功","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();
}
// 验签已通过:按 X-Cbc-Nonce 去重后再解析 body,处理 data
const notify = JSON.parse(req.body);
res.type('application/json').send('{"status":200,"msg":"请求成功","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();
}
// 验签已通过:按 X-Cbc-Nonce 去重后再解析 body,处理 data
return ResponseEntity.ok("{\"status\":200,\"msg\":\"请求成功\",\"data\":{\"success_data\":\"success\"}}");
}
商户应答示例:
{
"status": 200,
"msg": "请求成功",
"data": {
"success_data": "success"
}
}
- 商户加入监控的地址上发生交易,平台将请求该接口,由商户响应
- 若商户没有正确返回结果,平台将会重试请求,直到得到正确返回或者时间超过1小时。重试时间,第30秒、第1分钟、第3分钟、第7分钟、第15分钟、第25分钟、第40分钟、第60分钟。
HTTP Request
POST: 具体回调地址,由商户提供给平台方
请求参数
请求 Header 与接收端校验步骤见回调与复核签名。先用平台公钥验签,通过后再解析 body;下表为 body 中的字段。
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| data | 是 | object | 交易信息对象 |
| data.address | 是 | string | 商户监控的地址 |
| data.amount | 是 | string | 金额 |
| data.chain | 是 | string | 主链名 |
| data.coin | 是 | string | 币名 |
| data.confirm_count | 是 | integer | 区块确认数 |
| data.gas_fee | 是 | string | 交易gas费 |
| data.status | 是 | integer | 状态:0=待确认,1=已确认,2=异常 |
| data.status_msg | 否 | string | 失败原因,status=2 时下发 |
| data.time | 是 | integer | 交易区块的时间戳(单位秒) |
| data.token_address | 否 | string | 合约地址,主链币种该值为空 |
| data.transaction_type | 是 | integer | 地址交易类型:1=转入,2=转出 |
| data.txid | 是 | string | 链上交易hash |
返回参数说明
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| status | 是 | integer | 返回状态码,200为正常 |
| msg | 是 | string | 状态码描述 |
| data | 是 | object | 返回数据 |
| data.success_data | 是 | string | 业务上确认该回调处理成功,如果返回不是'success',平台将间隔一段时间后重试请求 |