> For the complete documentation index, see [llms.txt](https://docs.misttrack.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.misttrack.io/api-endpoints/get-risk-score-async-api-v3.md).

# Get Risk Score(Async API) V3

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 related to the address in question. Therefore, all tokens owned by the address will receive the same score.

## 1. Create Task API

#### HTTP Request

```shell
POST https://openapi.misttrack.io/v3/risk_score_create_task
```

**Parameters**

<table><thead><tr><th width="174.96484375">Parameter</th><th width="132.71484375">Type</th><th width="88.53125">Required</th><th>Description</th></tr></thead><tbody><tr><td>coin</td><td>string</td><td>yes</td><td>The coin to check for risk score, <strong>all optional values can be found</strong> <a href="/pages/4iOi28DV0NUUh4ETEpMx#multi-chain-support"><strong>here</strong></a></td></tr><tr><td>address</td><td>string</td><td>conditional</td><td>The address to check for risk score, required when <code>txid</code> is empty.</td></tr><tr><td>txid</td><td>string</td><td>conditional</td><td>The transaction hash to check for risk score, required when <code>address</code> is empty.</td></tr><tr><td>direction</td><td>string</td><td>no</td><td>Used for transaction hash queries. Optional values: <code>deposit</code>, <code>withdraw</code>. Default: <code>deposit</code>.</td></tr><tr><td>api_key</td><td>string</td><td>yes</td><td>Your API key</td></tr></tbody></table>

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

**Request Header**

Content-Type: application/json

**Request Demo**

```sh
curl --location 'https://openapi.misttrack.io/v3/risk_score_create_task'
--header 'Content-Type: application/json'
--data '{
    "address": "TNXoiAJ3dct8Fjg4M9fkLFh9S2v9TXc32G",
    "coin": "TRX",
    "api_key": "YourApiKey"
}'
```

```sh
curl --location 'https://openapi.misttrack.io/v3/risk_score_create_task'
--header 'Content-Type: application/json'
--data '{
    "txid": "c3fa08ba00eb1b59d4f2160065ab4bdea47fd50cbba0e0d48b4b11059c318d29",
    "coin": "TRX",
    "direction": "deposit",
    "api_key": "YourApiKey"
}'
```

**Response Parameters**

<table><thead><tr><th width="175.41015625">Parameter</th><th width="132.73046875">Type</th><th>Description</th></tr></thead><tbody><tr><td>has_result</td><td>bool</td><td>Whether the task has a result.</td></tr><tr><td>scanned_ts</td><td>int</td><td>Timestamp, indicating the time when the task result is generated.</td></tr><tr><td>task_id</td><td>string</td><td>Use this value to query the task result.</td></tr></tbody></table>

* Case-1: Task submitted, cache miss, the API response is as follows:

```json
{"success": true, "msg": "", "data": {"scanned_ts": 0, "has_result": false, "task_id": "fb4446aadfe0c2daf2181306c2f4434e78842b22a3a2dbfb3c2095331ade2cfc"}}
```

You can wait 1-10 seconds and then call the API `/v3/risk_score_query_task` to get the result.

* Case-2: Task submitted, cache hit, the API response is as follows:

```json
{"success": true, "msg": "", "data": {"scanned_ts": 1753093189, "has_result": true, "task_id": "fb4446aadfe0c2daf2181306c2f4434e78842b22a3a2dbfb3c2095331ade2cfc"}}
```

You can immediately call the API `/v3/risk_score_query_task` to get the result.

## 2. Query Task Result API

{% hint style="info" %}
This API has **NO** rate limit.
{% endhint %}

#### HTTP Request

```sh
GET https://openapi.misttrack.io/v3/risk_score_query_task
   ?task_id={task_id}
   &api_key=YourApiKey
```

**Parameters**

<table><thead><tr><th width="174.6484375">Parameter</th><th width="132.55078125">Type</th><th width="106.671875">Required</th><th>Description</th></tr></thead><tbody><tr><td>task_id</td><td>string</td><td>yes</td><td>The task id returned by <code>/v3/risk_score_create_task</code>.</td></tr><tr><td>api_key</td><td>string</td><td>yes</td><td>Your API key</td></tr></tbody></table>

**Response Parameters**

* The task is not completed.

```json
{"success": true, "msg": "TaskUnderRunning"}
```

* The task was not found.

```json
{"success": true, "msg": "TaskNotFound"}
```

* The task has been completed.

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

<table><thead><tr><th width="142.64453125">Parameter</th><th width="97.07421875">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="https://docs.misttrack.io/api-endpoints/get-risk-score-v3#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. 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>