# Get Risk Score(KYT/KYA) V3.0

#### 🌟 What’s New in Risk Score V3.0

1\. New in API Response

The API response introduces a new field `address_label`, which returns the entity label associated with the address (in txid + direction scenarios, it returns the label of the corresponding from/to address). It also adds a nested field `hop_dic` under `risk_detail`, which describes the multi-hop fund flow path between the queried address and each risk entity, representing the full transaction path by hop level, where the key is the hop level and the value is the list of addresses at that level.

2\. New in Query Parameters

A new query parameter `direction` is added and only takes effect when `txid` is provided. It is used to specify the transaction analysis direction (deposit / withdraw, default: deposit), determining whether risk calculation is performed from the incoming or outgoing side of the transaction.

Returns the risk score, risk detail list for a given address or transaction hash.

**Note**: This API calculates the risk score based on all transactions associated with the given address. All assets on the same blockchain will return the same result regardless of the coin parameter.

#### HTTP Request

```shell
GET https://openapi.misttrack.io/v3/risk_score
   ?coin=ETH
   &txid={txn hash}
   &direction=deposit
   &api_key=YourApiKey
```

```shell
GET https://openapi.misttrack.io/v3/risk_score
   ?coin=ETH
   &address={address}
   &api_key=YourApiKey
```

> Try this endpoint in your [browser](https://openapi.misttrack.io/v3/risk_score?coin=ETH\&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045\&api_key=YourApiKey) 🔗

{% tabs %}
{% tab title="Request" %}
Query Parameters

<table><thead><tr><th width="161.66666666666666">Parameter</th><th width="164">Type</th><th>Description</th></tr></thead><tbody><tr><td>coin</td><td>string</td><td>the coin to check for risk score, <strong>all optional values can be found</strong> <a href="../../openapi/overview#multi-chain-support"><strong>here</strong></a></td></tr><tr><td>address</td><td>string</td><td>the address to check for risk score, optional.</td></tr><tr><td>txid</td><td>string</td><td>the transaction hash to check for risk score, optional.</td></tr><tr><td>direction</td><td>string</td><td>optional values: <code>deposit</code>, <code>withdraw</code> , default: <code>deposit</code><br>Indicates transaction direction when <code>txid</code> is provided.</td></tr><tr><td>api_key</td><td>string</td><td>your api key</td></tr></tbody></table>

{% hint style="info" %}
Provide either `address` or `txid` as the target. Do not both.
{% endhint %}
{% endtab %}

{% tab title="Response" %}
Response Data Parameters

<table><thead><tr><th width="210">Parameter</th><th width="107.66666666666666">Type</th><th>Description</th></tr></thead><tbody><tr><td>score</td><td>int</td><td>Risk score of the queried address. Range: 3–100.</td></tr><tr><td>hacking_event</td><td>string</td><td>Related security incident associated with the address (if any).</td></tr><tr><td>detail_list</td><td>list</td><td>List of risk indicators associated with the address.</td></tr><tr><td>risk_level</td><td>string</td><td>Risk level, <a href="#risk-level-guide">Low / Moderate / High / Severe</a></td></tr><tr><td>risk_detail</td><td>list</td><td>Detailed breakdown of risk exposures used in score calculation.</td></tr><tr><td>address_label</td><td>string</td><td>Entity label of the queried address.<br>When <code>txid</code> and <code>direction</code> are provided, this refers to the label of the from or to address in the transaction.</td></tr><tr><td>risk_report_url</td><td>string</td><td>URL to download the MistTrack AML risk report (PDF) for this query.</td></tr></tbody></table>

Parameters for `risk_detail`

<table><thead><tr><th width="142.8359375">Parameter</th><th width="88.26953125">Type</th><th>Description</th></tr></thead><tbody><tr><td>entity</td><td>string</td><td>Name of the associated risk entity (e.g., garantex.io). This field is not enumerable.</td></tr><tr><td>risk_type</td><td>string</td><td><ul><li>sanctioned_entity</li><li>illicit_activity</li><li>mixer</li><li>gambling</li><li>risk_exchange</li><li>bridge</li></ul></td></tr><tr><td>exposure_type</td><td>string</td><td><ul><li>direct</li><li>indirect</li></ul></td></tr><tr><td>hop_num</td><td>int</td><td>Number of hops between the queried address and the risk entity. Minimum value: 1.</td></tr><tr><td>hop_dic</td><td>dict</td><td>Represents the transaction path between the queried address and the risk entity. Keys indicate hop levels, and values are arrays of addresses at each step.</td></tr><tr><td>volume</td><td>float</td><td>Total transaction volume associated with the risk entity (in USD).</td></tr><tr><td>percent</td><td>float</td><td>Proportion of this risk exposure relative to the total transaction volume.</td></tr></tbody></table>

Sample Response

```json
{
  "success": true,
  "msg": "",
  "data": {
    "score": 75,
    "hacking_event": "",
    "detail_list": [
      "Involved Illicit Activity",
      "Interact With High-risk Tag Address"
    ],
    "risk_level": "High",
    "risk_detail": [
      {
        "entity": "huionepay",
        "risk_type": "sanctioned_entity",
        "volume": 2373.904,
        "hop_num": 2,
        "exposure_type": "indirect",
        "hop_dic": {
          "1": [
            "huionepay"
          ],
          "2": [
            "TExZLkqhytVwJ3Dbcsp16u91f2oFTD1VEQ"
          ],
          "3": [
            "TU9SQJFv8imPtuuFesyAdwM1GVJTjBwFmn"
          ]
        },
        "percent": 45.652
      },
      {
        "entity": "www.hwdb.la",
        "risk_type": "sanctioned_entity",
        "volume": 113.674,
        "hop_num": 3,
        "exposure_type": "indirect",
        "hop_dic": {
          "1": [
            "www.hwdb.la"
          ],
          "2": [
            "THGBqCF4usjVB86zUuX9fiSwqQxaVUSRkB"
          ],
          "3": [
            "TExZLkqhytVwJ3Dbcsp16u91f2oFTD1VEQ"
          ],
          "4": [
            "TU9SQJFv8imPtuuFesyAdwM1GVJTjBwFmn"
          ]
        },
        "percent": 2.186
      },
      {
        "entity": "xinbi guarantee",
        "risk_type": "sanctioned_entity",
        "volume": 30.874,
        "hop_num": 3,
        "exposure_type": "indirect",
        "hop_dic": {
          "1": [
            "xinbi guarantee"
          ],
          "2": [
            "TPZpqQpkV35Y1YXuYDJsZZkiEefCrrGGfA"
          ],
          "3": [
            "TExZLkqhytVwJ3Dbcsp16u91f2oFTD1VEQ"
          ],
          "4": [
            "TU9SQJFv8imPtuuFesyAdwM1GVJTjBwFmn"
          ]
        },
        "percent": 0.594
      },
      {
        "entity": "USDT Banned Address",
        "risk_type": "illicit_activity",
        "volume": 22.372,
        "hop_num": 3,
        "exposure_type": "indirect",
        "hop_dic": {
          "1": [
            "TNXubajgkYKmQ2rCG3oqR3HDjYZWZJYxxg"
          ],
          "2": [
            "TENjUs6TYuxjmQxMBkP9g2cg9Ug5mJrWCz"
          ],
          "3": [
            "TExZLkqhytVwJ3Dbcsp16u91f2oFTD1VEQ"
          ],
          "4": [
            "TU9SQJFv8imPtuuFesyAdwM1GVJTjBwFmn"
          ]
        },
        "percent": 0.43
      },
      {
        "entity": "Illegal Services",
        "risk_type": "illicit_activity",
        "volume": 10.296,
        "hop_num": 3,
        "exposure_type": "indirect",
        "hop_dic": {
          "1": [
            "TUfBKrEKh58QYGTCkfSBj8zYP9iHK9KXTW"
          ],
          "2": [
            "TUJBPo6rGCnGEsfuSRgQ585GE28ydu1Ef5"
          ],
          "3": [
            "TExZLkqhytVwJ3Dbcsp16u91f2oFTD1VEQ"
          ],
          "4": [
            "TU9SQJFv8imPtuuFesyAdwM1GVJTjBwFmn"
          ]
        },
        "percent": 0.198
      },
      {
        "entity": "Guarantee Merchant",
        "risk_type": "illicit_activity",
        "volume": 7.476,
        "hop_num": 3,
        "exposure_type": "indirect",
        "hop_dic": {
          "1": [
            "TMrtQHj7C2QmSG3YqwN3Kdv4MxeBJpfTV5"
          ],
          "2": [
            "TENjUs6TYuxjmQxMBkP9g2cg9Ug5mJrWCz"
          ],
          "3": [
            "TExZLkqhytVwJ3Dbcsp16u91f2oFTD1VEQ"
          ],
          "4": [
            "TU9SQJFv8imPtuuFesyAdwM1GVJTjBwFmn"
          ]
        },
        "percent": 0.144
      },
      {
        "entity": "Phishing",
        "risk_type": "illicit_activity",
        "volume": 5.429,
        "hop_num": 3,
        "exposure_type": "indirect",
        "hop_dic": {
          "1": [
            "TKt83wLwr7dB8NoF5D61Yd1fdmvPWEbiav"
          ],
          "2": [
            "TUJ7Whcypxfapp1riCTXHS9gewh8uqQea9"
          ],
          "3": [
            "TExZLkqhytVwJ3Dbcsp16u91f2oFTD1VEQ"
          ],
          "4": [
            "TU9SQJFv8imPtuuFesyAdwM1GVJTjBwFmn"
          ]
        },
        "percent": 0.104
      },
      {
        "entity": "DGCX(Xinkangjia) Scam",
        "risk_type": "illicit_activity",
        "volume": 5.334,
        "hop_num": 3,
        "exposure_type": "indirect",
        "hop_dic": {
          "1": [
            "TJsboummq5ipC4PRigGuW7zi2TUK5PHhFN"
          ],
          "2": [
            "TTeYJS4RihjG7LyZHCBPfLvwj75mTtDf38"
          ],
          "3": [
            "TExZLkqhytVwJ3Dbcsp16u91f2oFTD1VEQ"
          ],
          "4": [
            "TU9SQJFv8imPtuuFesyAdwM1GVJTjBwFmn"
          ]
        },
        "percent": 0.103
      }
    ],
    "address_label": "",
    "risk_report_url": "https://light.misttrack.io/riskReport/TU9SQJFv8imPtuuFesyAdwM1GVJTjBwFmn?token=43fb70ee-76a2-40b6-95a8-d67205d96f0e"
  }
}
```

{% endtab %}
{% endtabs %}

### Risk Descriptions For `detail_list`

| Risk Item                                 | Risk Description                                                                                                                           |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Malicious Address                         | Address directly involved in malicious events, example: DeFi protocol exploiters, centralized exchange hackers, sanctioned addresses, etc. |
| Suspected Malicious Address               | Address associated with malicious events                                                                                                   |
| High-risk Tag Address                     | High-risk entity address, example: Mixers, some nested exchanges, etc.                                                                     |
| Medium-risk Tag Address                   | Medium-risk entity address, example: Gambling, exchanges not requiring KYC, etc.                                                           |
| Mixer                                     | Mixer entity address, example: Tornado Cash, etc.                                                                                          |
| Sanctioned Entity                         | Sanctioned entity address, example: garantex, etc.                                                                                         |
| Risk Exchange                             | Exchanges that do not require KYC                                                                                                          |
| Gambling                                  | Gambling entity address                                                                                                                    |
| Involved Theft Activity                   | Address involved in theft events                                                                                                           |
| Involved Ransom Activity                  | Address involved in ransom events                                                                                                          |
| Involved Phishing Activity                | Address involved in phishing events                                                                                                        |
| Involved Illicit Activity                 | Address involved in illicit activity, example: money laundering, etc.                                                                      |
| Interact With Malicious Address           | Interactions with malicious address                                                                                                        |
| Interact With Suspected Malicious Address | Interactions with suspected malicious address                                                                                              |
| Interact With High-risk Tag Address       | Interactions with high-risk address                                                                                                        |
| Interact With Medium-risk Tag Addresses   | Interactions with medium-risk address                                                                                                      |

### Risk Level Guide

<table><thead><tr><th width="163">Risk Level</th><th width="138">Risk Score</th><th>Suggested Operations</th></tr></thead><tbody><tr><td>Severe</td><td>91 ~ 100</td><td>Prohibit withdrawals &#x26; trade, and report address immediately</td></tr><tr><td>High</td><td>71 ~ 90</td><td>Maintain high level surveillance, and analyze via MistTrack AML platform or OpenAPI to conduct transaction analysis</td></tr><tr><td>Moderate</td><td>31 ~ 70</td><td>Moderate supervision required</td></tr><tr><td>Low</td><td>0 ~ 30</td><td>Minimal supervision required</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.misttrack.io/api-endpoints/get-risk-score-v3.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.