KYA API

1. Chaintool API

1.1 API Authentication

All API requests sent to the Chaintool service have to include an independent HTTP Header item. For example:

 curl --location --request POST 'https://api.chaintool.ai/{product}/{version}/{method}' \
    --header 'Content-Type: application/json' \
    --header 'TOKEN:${your api token}'

1.2 API Result

All results returned by the Chaintool service APIs are in JSON format and must contain two fields, namely errorCode and message.

The status field returns a number, and its specific meanings are explained in the following table.

Status	Description
200	Successful request
400	Bad request
403	Forbidden
404	Not found
406	Not acceptable
409	Conflict
500	Internal server error
503	Service unavailable error
504	Request timeout

The message field represents the information of currently being processed by the server. When the status field returns 200, it is fixed as success. Otherwise, the message field contains a specific description of the server error content.

2. KYA API

2.1 KYA API Request

This API is called via HTTPS POST method. The query params will be placed in the request url.

URL: https://api.chaintool.ai/kya/v2/risk_score?network={network}&address={address}

• Request Params:

Param	Is Required	Description
network	true	The blockchain network of the wallet address needs to be screened
address	true	The wallet address needs to be screened.

• Enumeration Values for Request Params:

Network
Bitcoin
Ethereum
Tron
Polygon
Base
BSC

• Request Example:

curl --location --request POST 'https://api.chaintool.ai/kya/v2/risk_score?network=Ethereum&address=0x3d2a23ead4a6e2b8ff973250e56d70cc78353c50' \
    --header 'Content-Type: application/json' \
    --header 'TOKEN: {your token}'

2.2 KYA API Result

• Result Example:

{
    "address": "0xad1cb38570337eb24f5346393f9b83363870d436",
    "riskLevel": "Low",
    "suspiciousActivityReasons": "",
    "confidence": "Relatively certain",
    "errorCode": 200,
    "message": "SUCCESS",
    "example": false,
    "network": "Ethereum",
    "sendExposure": "3.0",
    "recordId": 37,
    "scoreSuspiciousActivity": "3.0",
    "receivingExposure": "3.0",
    "riskScore": "3.0",
    "asset": "ETH",
    "category": "3"
}

• Result Params:

Param	Is Require	Description
asset	true	Asset/token
address	true	Wallet address
balance	true	The asset of the balance of a wallet address
usdAmount	true	The USD value of the balance of a wallet address
riskScore	true	Overall money laundering risk score
category	true	Sub-item 1: The risk score of category
tag	true	The tag(category) of wallet address
riskLevel	true	Deprecated
sendExposure	true	Sub-item 2: The risk score of sending exposure
receivingExposure	true	Sub-item 3: The risk score of receiving exposure
scoreSuspiciousActivity	true	Sub-item 4: The risk score of suspicious activity
suspiciousActivityReasons	false	The risk score of suspicious activity
accuracyLevel	false	Deprecated
remarkReason	false	Deprecated
remarkOrg	false	Deprecated

• Additional Explanation：

  • We recommend that customers focus on the riskScore returned by the API to make further risk decisions.

  • The ML risk score ranges from 1 to 10. Scores in the range [1, 3.5) indicate low risk (Low), and we suggest allowing operations associated with this address. Scores in the range [3.5, 6.5) indicate medium risk (Medium), and we recommend making decisions based on the individual scores of each subcategory and considering your specific business requirements. Scores in the range [6.5, 8.5) indicate high risk (High), and we advise intercepting operations associated with this address, conducting a review, and then deciding whether to allow them. Scores in the range [8.5, 10] indicate severe risk (Severe), and we recommend intercepting operations associated with this address and conducting a thorough review.

    • Sub-item 1 - Risk score of categories. We identified the categories of the wallet address and evaluate the category risk score based on the risk level of the categories in the real world.

      • Sub-item 2 - Risk score of the sending exposure. We consider the direct and indirect historical transaction and evaluate the sending exposure risk score based on categories of counterparts.

      • Sub-item 3 - Risk score of the receiving exposure. We consider the direct and indirect historical receiving transaction and evaluate the receiving exposure risk score based on categories of counterparts.

      • Sub-item 4 - Risk score of suspicious activity. We consider whether the target address has participated in various high-risk behaviors, such as, suspicious peel chain node, fast in and out transactions, cross-chain transactions, high-frequency small-value transactions, etc.

  • Know more information about ML risk score, please refer to ML Risk Score.