Address check

Crypto2B lets the client system check the risk level (AML) of any crypto address before performing an operation with it. A typical scenario is checking an address the user entered in a withdrawal form, before the withdrawal request is created.

The check is performed asynchronously. The client system registers a check by calling the /addressChecks/create API, and gets the result in one of two ways:

1. Handle the callback from Crypto2B with the check result (see Callbacks).
2. Call the /addressChecks/create API again with the same parameters until the result is received.

Address check process

Sequence of actions

1. The user enters an address in the client system, for example, for a withdrawal.
2. The client system sends Crypto2B a request to check the address, specifying the currency, transport protocol, and address.
3. Crypto2B validates the request parameters, the client's restrictions, and the availability of funds to pay for the check, registers the check, and returns its identifier checkId with status Pending.
4. Crypto2B performs the address check and determines its risk level.
5. When the check is complete, Crypto2B deducts the check fee from the client's balance and moves the check to status Completed.
6. If the client system uses the callback mechanism, Crypto2B sends a callback with the check result.
7. Otherwise, the client system repeats the request with the same parameters and receives the result with status Completed.
8. The client system decides whether to accept the address based on the amlRiskGrade risk level.

Request

POST /api/v1/addressChecks/create

Parameter	Type	Required	Description
currencyShortName	string	yes	Short currency name, for example USDT
transportProtocol	string	yes	Transport protocol, for example Tron
address	string	yes	Address to check, no more than 200 characters

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

Response

Check registered or in progress — 202 Accepted

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

Check completed — 200 OK

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

Field	Description
checkId	Unique check identifier
status	Check status: Pending, Completed
amlRiskGrade	Address risk level (see Dictionaries). Populated only when status is Completed
description	Address description based on the check result, if available
fromCache	true if a previously obtained result is returned (see Repeated checks)

Errors

HTTP code	Error code	Description
400	—	Request parameter validation error, including an invalid address format for the specified currency and protocol
400	INVALID_CURRENCY	Currency not found or not supported on the specified protocol
400	INVALID_TRANSPORT_PROTOCOL	Transport protocol not found
402	INSUFFICIENT_BALANCE	The client's balance does not have enough funds to pay for the check
422	OPERATION_RESTRICTED	Address check is not available for this client
422	TARIFF_NOT_FOUND	No tariff is configured for the client

Check statuses

Status	Description
Pending	The check is registered and in progress
Completed	The check completed successfully, the risk level was obtained, and the fee was charged
Error	The check failed due to an error. The fee is not charged
Unknown	The check result could not be determined, for example, the check is not supported for the specified currency. The fee is not charged

info

The Error and Unknown statuses are only delivered in the callback. If the request is repeated after such a check, Crypto2B registers a new check and returns 202 Accepted with a new checkId.

Repeated checks

The result of a successful check is stored for 10 minutes. A repeated request with the same currency, protocol, and address within this time:

• while the check is in progress — returns 202 Accepted with the same checkId; no new check is created;
• after completion — returns 200 OK with the stored result and fromCache: true; the fee is not charged again.

After 10 minutes, the request registers a new check, for which the fee is charged.

tip

If the client system does not use callbacks, it is recommended to repeat the request every few seconds until 200 OK is received. A change in the checkId in the response means the previous check ended in an error and a new one was registered.

Check fee

For each successfully completed check, a fixed fee in USD is deducted from the client's balance; its amount is determined by the client's tariff (see Billing).

• The fee is charged when the check completes with status Completed.
• The fee is deducted from the client's stablecoin balance (USDT or USDC) at the exchange rate at the time of the charge. The amount and currency of the charge are sent in the callback.
• If neither stablecoin balance has sufficient funds, the request is rejected with code 402.
• No fee is charged for checks with status Error or Unknown.
• Address check charges are shown in the personal account's list of operations.

Callback

If a callback URL is configured for the client, Crypto2B sends a callback when the check completes in any final status: Completed, Error, Unknown.

{
  "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
  }
}

Field	Description
type	Operation type: AddressCheck
checkId	Check identifier
address	Checked address
status	Check status: Completed, Error, Unknown
amlRiskGrade	Address risk level. Populated only when status is Completed
description	Address description based on the check result, if available
currency	Short currency name
protocol	Transport protocol
feeAmount	Fee amount charged, in the feeCurrencyShortName currency. null if no fee was charged
feeCurrencyShortName	Currency in which the fee was charged
timestamp	Date and time the callback was generated (ISO 8601)
errorCode	Error code for the Error and Unknown statuses
errorMessage	Error description for the Error and Unknown statuses

Callback error codes

Code	Status	Description
INSUFFICIENT_BALANCE	Error	At the time of the charge, the client's balance did not have enough funds to pay for the check
ANTIFRAUD_ERROR	Error	Error while performing the check
ANTIFRAUD_INVALID_RESULT	Unknown	The check completed without determining a risk level
CURRENCY_NOT_SUPPORTED	Unknown	Address check is not supported for the specified currency or protocol
INTERNAL_ERROR	Error	Internal processing error

note

For address check callbacks, uniqueness is determined by the combination of type and checkId, not type and id as for other operations.