机器翻译

本页面使用机器翻译。如有任何不一致之处，请参阅英文文档。

地址检查

Crypto2B 允许客户端系统在对任意加密货币地址执行操作之前，检查该地址的风险等级(AML)。典型场景是在创建提现请求之前，检查用户在提现表单中输入的地址。

检查是异步执行的。客户端系统通过调用 /addressChecks/create API 注册一次检查，并通过以下两种方式之一获取结果：

处理来自 Crypto2B 的带有检查结果的回调（参见回调）。
使用相同的参数再次调用 /addressChecks/create API，直到收到结果。

地址检查流程

操作顺序

用户在客户端系统中输入地址，例如用于提现。
客户端系统向 Crypto2B 发送地址检查请求，指定币种、传输协议和地址。
Crypto2B 验证请求参数、客户的限制条件以及是否有足够资金支付检查费用，注册该检查，并返回其标识符 checkId，状态为 Pending。
Crypto2B 执行地址检查并确定其风险等级。
检查完成后，Crypto2B 从客户余额中扣除检查费用，并将检查状态置为 Completed。
如果客户端系统使用回调机制，Crypto2B 会发送带有检查结果的回调。
否则，客户端系统使用相同的参数重复该请求，并获取状态为 Completed 的结果。
客户端系统根据 amlRiskGrade 风险等级决定是否接受该地址。

请求

POST /api/v1/addressChecks/create

参数	类型	是否必填	描述
`currencyShortName`	string	是	币种简称，例如 `USDT`
`transportProtocol`	string	是	传输协议，例如 `Tron`
`address`	string	是	待检查的地址，不超过 200 个字符

{
  "currencyShortName": "USDT",
  "transportProtocol": "Tron",
  "address": "TJYeasypBnB2x5hLTpYPQZ6YR9ZL3hLj6b"
}

响应

检查已注册或正在进行 — `202 Accepted`

{
  "data": {
    "checkId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "Pending",
    "amlRiskGrade": null,
    "description": null,
    "fromCache": null
  }
}

检查完成 — `200 OK`

{
  "data": {
    "checkId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "Completed",
    "amlRiskGrade": "Low",
    "description": "Exchange wallet",
    "fromCache": true
  }
}

字段	描述
`checkId`	唯一的检查标识符
`status`	检查状态：`Pending`、`Completed`
`amlRiskGrade`	地址风险等级（参见字典）。仅当状态为 `Completed` 时才会填充
`description`	基于检查结果的地址描述（如有）
`fromCache`	如果返回的是之前获取的结果，则为 `true`（参见重复检查）

错误

HTTP 代码	错误代码	描述
400	—	请求参数校验错误，包括指定币种和协议下的地址格式无效
400	`INVALID_CURRENCY`	未找到该币种，或该币种在指定协议下不受支持
400	`INVALID_TRANSPORT_PROTOCOL`	未找到该传输协议
402	`INSUFFICIENT_BALANCE`	客户余额不足以支付检查费用
422	`OPERATION_RESTRICTED`	该客户不可使用地址检查功能
422	`TARIFF_NOT_FOUND`	未为该客户配置资费方案

检查状态

状态	描述
`Pending`	检查已注册，正在进行中
`Completed`	检查成功完成，已获取风险等级，并已收取费用
`Error`	检查因错误而失败，不收取费用
`Unknown`	无法确定检查结果，例如指定币种不支持该检查，不收取费用

信息

Error 和 Unknown 状态仅通过回调传递。如果在此类检查之后重复该请求，Crypto2B 会注册一次新的检查，并返回带有新 checkId 的 202 Accepted。

重复检查

成功检查的结果会保存 10 分钟。在此时间内，使用相同币种、协议和地址重复请求：

若检查仍在进行中 — 返回带有相同 checkId 的 202 Accepted；不会创建新的检查；
若检查已完成 — 返回带有已保存结果的 200 OK，且 fromCache: true；不会再次收取费用。

超过 10 分钟后，该请求将注册一次新的检查，并收取相应费用。

提示

如果客户端系统不使用回调，建议每隔几秒重复一次请求，直到收到 200 OK。响应中 checkId 发生变化，意味着上一次检查以错误结束，并已注册了一次新的检查。

检查费用

每次成功完成检查，都会从客户余额中扣除一笔以美元计价的固定费用，其金额由客户的资费方案决定（参见计费）。

检查以 Completed 状态完成时收取费用。
费用从客户的稳定币余额（USDT 或 USDC）中按扣费时的汇率扣除。扣费的金额和币种会在回调中发送。
如果两种稳定币余额均不足，请求将被拒绝，返回代码 402。
状态为 Error 或 Unknown 的检查不收取费用。
地址检查的扣费会显示在个人账户的操作列表中。

回调

如果为客户配置了回调 URL，当检查以任意最终状态完成时（Completed、Error、Unknown），Crypto2B 会发送回调。

{
  "data": {
    "type": "AddressCheck",
    "checkId": "550e8400-e29b-41d4-a716-446655440000",
    "address": "TJYeasypBnB2x5hLTpYPQZ6YR9ZL3hLj6b",
    "status": "Completed",
    "amlRiskGrade": "Low",
    "description": "Exchange wallet",
    "currency": "USDT",
    "protocol": "Tron",
    "feeAmount": 0.5,
    "feeCurrencyShortName": "USDT",
    "timestamp": "2024-01-15T10:30:00Z",
    "errorCode": null,
    "errorMessage": null
  }
}

字段	描述
`type`	操作类型：`AddressCheck`
`checkId`	检查标识符
`address`	被检查的地址
`status`	检查状态：`Completed`、`Error`、`Unknown`
`amlRiskGrade`	地址风险等级。仅当状态为 `Completed` 时才会填充
`description`	基于检查结果的地址描述（如有）
`currency`	币种简称
`protocol`	传输协议
`feeAmount`	以 `feeCurrencyShortName` 指定的币种收取的费用金额。如果未收取费用则为 `null`
`feeCurrencyShortName`	收取费用所使用的币种
`timestamp`	回调生成的日期和时间（ISO 8601）
`errorCode`	`Error` 和 `Unknown` 状态对应的错误代码
`errorMessage`	`Error` 和 `Unknown` 状态对应的错误描述

回调错误代码

代码	状态	描述
`INSUFFICIENT_BALANCE`	`Error`	扣费时客户余额不足以支付检查费用
`ANTIFRAUD_ERROR`	`Error`	执行检查时发生错误
`ANTIFRAUD_INVALID_RESULT`	`Unknown`	检查已完成，但未能确定风险等级
`CURRENCY_NOT_SUPPORTED`	`Unknown`	指定币种或协议不支持地址检查
`INTERNAL_ERROR`	`Error`	内部处理错误

备注

对于地址检查回调，唯一性由 type 和 checkId 的组合确定，而不像其他操作那样由 type 和 id 确定。

地址检查流程​

操作顺序​

请求​

响应​

检查已注册或正在进行 — 202 Accepted​

检查完成 — 200 OK​

错误​

检查状态​

重复检查​

检查费用​

回调​

回调错误代码​