> For the complete documentation index, see [llms.txt](https://beosinofficials-organization.gitbook.io/beosin-api-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://beosinofficials-organization.gitbook.io/beosin-api-documentation/api-endpoints/kya-v5.md).

# KYA V5

### Description

Conduct a comprehensive risk assessment of the address.

* Check if the address itself is a risky entity.
* Check if the incoming funds for the address are from high-risk entities.
* Check if the outgoing funds of the address are going to a risky entity.

Use cases

* Use this API to evaluate when the user is on board.
* Use this API to perform a risk assessment on the withdrawal address used by the user when requesting a withdrawal.
* Use this API to assess users during regular risk screening.

### Basic Info

> * Request Method: GET
> * API URL: <https://api.beosin.com/api/v5/kyt/address/risk>
> * Content-Type: application/json
> * Authentication: SIGN
> * Response Time: <30s

### **Header** Request Parameter

<table><thead><tr><th width="150">Parameter</th><th width="193">Required Field (Y/N)</th><th width="157">Parameter Type</th><th width="250">Description</th></tr></thead><tbody><tr><td><a href="/beosin-api-documentation/getting-started/verification.md">APPID</a></td><td>Y</td><td>String</td><td>Unique authentication APPID assigned by KYT system</td></tr><tr><td><a href="/beosin-api-documentation/getting-started/verification.md">APP-SECRET</a></td><td>Y</td><td>String</td><td>Unique authentication APP-SECRET assigned by KYT system</td></tr></tbody></table>

### Query Parameter

| Parameter | Required(Y/N) | Data Type | Description                                                    |
| --------- | ------------- | --------- | -------------------------------------------------------------- |
| chainId   | Y             | String    | Blockchain ID                                                  |
| address   | Y             | String    | Wallet address                                                 |
| token     | N             | String    | Token contract address. Defaults to native token if left blank |

### Return Parameter

<table><thead><tr><th width="247">Parameter</th><th width="168">Data Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>Number</td><td>Return id</td></tr><tr><td>code</td><td>Integer</td><td>Status code</td></tr><tr><td>msg</td><td>String</td><td>Result message</td></tr><tr><td>data</td><td>Object</td><td>Result set</td></tr><tr><td>data.score</td><td>BigDecimal</td><td>Total score</td></tr><tr><td>data.riskLevel</td><td>String</td><td>Risk level (Severe, High, Medium, Low)</td></tr><tr><td>data.incomingScore</td><td>BigDecimal</td><td>Incoming fund score</td></tr><tr><td>data.incomingLevel</td><td>String</td><td>Incoming fund risk level</td></tr><tr><td>data.incomingDetail</td><td>List</td><td>Incoming fund risk details</td></tr><tr><td>data.incomingDetail[].strategyName</td><td>String</td><td>Strategy name</td></tr><tr><td>data.incomingDetail[].riskLevel</td><td>String</td><td>Risk level</td></tr><tr><td>data.incomingDetail[].exposure</td><td>String</td><td>Exposure type (Direct/Indirect)</td></tr><tr><td>data.incomingDetail[].hops</td><td>Integer</td><td>Hops</td></tr><tr><td>data.incomingDetail[].rate</td><td>BigDecimal</td><td>Proportion of risky funds</td></tr><tr><td>data.incomingDetail[].amount</td><td>BigDecimal</td><td>Amount of risky funds</td></tr><tr><td>data.incomingDetail[].entityDetails</td><td>List</td><td>Entity details</td></tr><tr><td>data.incomingDetail[].entityDetails[].entityName</td><td>String</td><td>Entity name</td></tr><tr><td>data.incomingDetail[].entityDetails[].hops</td><td>Integer</td><td>Hops</td></tr><tr><td>data.incomingDetail[].entityDetails[].purificationAmountU</td><td>BigDecimal</td><td>Purified amount</td></tr><tr><td>data.incomingDetail[].entityDetails[].purificationRate</td><td>BigDecimal</td><td>Purification proportion</td></tr><tr><td>data.outgoingScore</td><td>BigDecimal</td><td>Outgoing fund score</td></tr><tr><td>data.outgoingLevel</td><td>String</td><td>Outgoing fund risk level</td></tr><tr><td>data.outgoingDetail</td><td>List</td><td>Outgoing fund risk details</td></tr><tr><td>data.riskTagScore</td><td>BigDecimal</td><td>Risk tag score</td></tr><tr><td>data.riskTagLevel</td><td>String</td><td>Risk tag level</td></tr><tr><td>data.riskTagDetails</td><td>List</td><td>Risk tag details</td></tr><tr><td>data.entities</td><td>List</td><td>Entity list</td></tr><tr><td>data.points</td><td>List</td><td>Topology node details</td></tr><tr><td>data.points[].id</td><td>String</td><td>Node ID</td></tr><tr><td>data.points[].platform</td><td>String</td><td>Platform</td></tr><tr><td>data.points[].address</td><td>String</td><td>Address Hash</td></tr><tr><td>data.points[].tokens</td><td>Set&#x3C;String></td><td>Token set</td></tr><tr><td>data.points[].iniPoint</td><td>Boolean</td><td>Whether it is the source node</td></tr><tr><td>data.points[].depth</td><td>Integer</td><td>Hierarchy</td></tr><tr><td>data.points[].addressTag</td><td>Object</td><td>Tag</td></tr><tr><td>data.points[].hitStrategy</td><td>Boolean</td><td>Whether the strategy is hit</td></tr><tr><td>data.points[].direction</td><td>String</td><td>Direction</td></tr><tr><td>data.points[].isInCustomerBlackList</td><td>Boolean</td><td>Whether in the custom blacklist</td></tr><tr><td>data.points[].effectiveTag</td><td>Object</td><td>address tag</td></tr><tr><td>data.lines</td><td>List</td><td>Topology link details</td></tr><tr><td>data.lines[].fromId</td><td>String</td><td>Source address ID</td></tr><tr><td>data.lines[].toId</td><td>String</td><td>Target address ID</td></tr><tr><td>data.lines[].txValueU</td><td>BigDecimal</td><td>Transaction amount</td></tr><tr><td>data.lines[].totalPercent</td><td>BigDecimal</td><td></td></tr><tr><td>data.lines[].addressExtendTypes</td><td>Set&#x3C;String></td><td>Transaction types included online: INI (Source Point), COMMON (Standard Transaction), SWAP (Currency Exchange), CROSS (Cross-Chain)</td></tr><tr><td>data.lines[].thisDeptPercent</td><td>BigDecimal</td><td>The percentage of the transaction amount relative to the total amount at that address.</td></tr><tr><td>data.lines[].currencies</td><td>List</td><td>Currency list</td></tr><tr><td>data.lines[].currencies[].value</td><td>BigDecimal</td><td>Native token quantity</td></tr><tr><td>data.lines[].currencies[].valueU</td><td>BigDecimal</td><td>Fiat equivalent amount</td></tr><tr><td>data.lines[].currencies[].currencyName</td><td>String</td><td>Currency name</td></tr><tr><td>data.lines[].currencies[].currencyTokenAddress</td><td>String</td><td>Token contract address</td></tr><tr><td>data.lines[].currencies[].platformEnum</td><td>String</td><td>Platform</td></tr><tr><td>data.topologyTooLarge</td><td>Boolean</td><td>Whether topology node count exceeds the limit (>500)</td></tr></tbody></table>

### Request Example

```
GET https://api.beosin.com/api/v5/kyt/address/risk?chainId=1&address=0x3a53da473cb44bc3409eda6778781d2a035b2ea6&token=0xdac17f958d2ee523a2206206994597c13d831ec7
```

### Response Example

```json
{
"id": 2071864046755426304,
"code": 200,
"msg": "success",
"data": {
"score": 61.31,
"riskLevel": "Severe",
"incomingScore": 55.11,
"incomingLevel": "High",
"incomingDetail": [
      {
"strategyName": "Sanctions",
"riskLevel": "High",
"exposure": "Indirect",
"hops": 2,
"rate": 0.002568,
"amount": 51.005574,
"entityDetails": [
          {
"entityName": "Nobitex.ir",
"hops": 2,
"purificationAmountU": 51.005574,
"purificationRate": 0.002568
          }
        ]
      }
    ],
"outgoingScore": 61.31,
"outgoingLevel": "Severe",
"outgoingDetail": [
      {
"strategyName": "Sanctions",
"riskLevel": "Severe",
"exposure": "Direct",
"hops": 1,
"rate": 0.0331,
"amount": 657.50266,
"entityDetails": [
          {
"entityName": "Nobitex.ir",
"hops": 1,
"purificationAmountU": 657.50266,
"purificationRate": 0.033102
          }
        ]
      },
      {
"strategyName": "Sanctions",
"riskLevel": "High",
"exposure": "Indirect",
"hops": 2,
"rate": 0.000715,
"amount": 14.19873,
"entityDetails": [
          {
"entityName": "Nobitex.ir",
"hops": 2,
"purificationAmountU": 14.19873,
"purificationRate": 0.000715
          }
        ]
      }
    ],
"riskTagScore": null,
"riskTagLevel": null,
"riskTagDetails": [
"High Risk Jurisdiction-FATF",
"Sanctions"
        ],
"entities": [
"Lazarus Group",
"HTX"
        ],
"points": [
      {
"id": "eth_0x3a53da473cb44bc3409eda6778781d2a035b2ea6",
"platform": "ETH",
"address": "0x3a53da473cb44bc3409eda6778781d2a035b2ea6",
"tokens": [
"",
"0xdac17f958d2ee523a2206206994597c13d831ec7"
        ],
"iniPoint": true,
"depth": 0,
"addressTag": null,
"hitStrategy": null,
"direction": null,
"inCustomerBlackList": false
      },
      {
"id": "eth_0x8d56f551b44a6da6072a9608d63d664ce67681a5",
"platform": "ETH",
"address": "0x8d56f551b44a6da6072a9608d63d664ce67681a5",
"tokens": [
""
        ],
"iniPoint": false,
"depth": 1,
"addressTag": {
"black": [
"High Risk Jurisdiction-FATF",
"Sanctions"
          ],
"projectService": [],
"financeService": [
"Exchange"
          ]
        },
"effectiveTag": {
"type": "Sanctions",
"addressTagType": "MALICIOUS",
"tagType": "Sanctions"
        },
"hitStrategy": true,
"direction": "FRONT",
"inCustomerBlackList": false
      }
    ],
"lines": [
      {
"fromId": "eth_0x3a53da473cb44bc3409eda6778781d2a035b2ea6",
"toId": "eth_0x3a53da473cb44bc3409eda6778781d2a035b2ea6",
"txValueU": 1907.674681,
"totalPercent": null,
"thisDeptPercent": 0.632,
"currencies": [
          {
"value": 1910.65219,
"valueU": 1907.674681,
"currencyName": "USDT",
"currencyTokenAddress": "0xdac17f958d2ee523a2206206994597c13d831ec7",
"platformEnum": "ETH"
          }
        ],
"addressExtendTypes": [
"COMMON", "SWAP"
        ],
      },
      {
"fromId": "eth_0x8d56f551b44a6da6072a9608d63d664ce67681a5",
"toId": "eth_0x3a53da473cb44bc3409eda6778781d2a035b2ea6",
"txValueU": 2183.364307,
"totalPercent": null,
"thisDeptPercent": 0.0512,
"currencies": [
          {
"value": 1.10640799,
"valueU": 2183.364307,
"currencyName": "ETH",
"currencyTokenAddress": "local",
"platformEnum": "ETH"
          }
        ],
"addressExtendTypes": [
"COMMON"
        ],
      }
    ],
"topologyTooLarge": false
  }
}
​
       

```