> 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/openapi/sandbox-api.md).

# Sandbox API

The Sandbox API returns predefined risk score results for integration testing.

Base URL:

```
https://sandbox-api.misttrack.io
```

### Authentication and Limits

All endpoints require `api_key`.

| Limit      | Value                    |
| ---------- | ------------------------ |
| Per second | 10 requests / API key    |
| Per day    | 10000 requests / API key |

Supported `coin` values:

<table><thead><tr><th width="89.078125">Coin</th><th width="345.03125">Level Coverage</th><th>Sample Count</th></tr></thead><tbody><tr><td>ETH</td><td><code>Severe</code>, <code>High</code>, <code>Moderate</code>, <code>Low</code></td><td>5</td></tr><tr><td>TRX</td><td><code>Severe</code>, <code>High</code>, <code>Moderate</code>, <code>Low</code></td><td>5</td></tr></tbody></table>

The `coin` value must match the sandbox target. ETH targets use `0x...` addresses or transaction hashes. TRX targets use `T...` addresses or 64-character transaction hashes without the `0x` prefix.

### 1. Get Risk Score

Returns the risk score result for a sandbox address or transaction hash.

```shell
GET https://sandbox-api.misttrack.io/v3/risk_score
```

#### Query Parameters

<table><thead><tr><th width="138.01953125">Parameter</th><th width="106.171875">Type</th><th width="125.16796875">Required</th><th>Description</th></tr></thead><tbody><tr><td>coin</td><td>string</td><td>yes</td><td>Supported values: <code>ETH</code>, <code>TRX</code>.</td></tr><tr><td>address</td><td>string</td><td>conditional</td><td>Sandbox address to query. Required when <code>txid</code> is empty.</td></tr><tr><td>txid</td><td>string</td><td>conditional</td><td>Sandbox transaction hash to query. Required when <code>address</code> is empty.</td></tr><tr><td>api_key</td><td>string</td><td>yes</td><td>Sandbox API key.</td></tr></tbody></table>

#### Request Example: Address

```shell
curl --location 'https://sandbox-api.misttrack.io/v3/risk_score?coin=ETH&address=0xadaf27611952c35de3ac46412225bc8cec66e2b6&api_key=YourApiKey'
```

#### Request Example: Transaction Hash

```shell
curl --location 'https://sandbox-api.misttrack.io/v3/risk_score?coin=ETH&txid=0x49a063b6f1c624f1c914241af8ecd1237fc09104987ea9c904eebfee74787a0b&api_key=YourApiKey'
```

```shell
curl --location 'https://sandbox-api.misttrack.io/v3/risk_score?coin=TRX&txid=3aa550c861c47bd955634126072e460965267ef424e4088a68d9c5368e03d789&api_key=YourApiKey'
```

#### Response Example

```json
{
  "success": true,
  "msg": "",
  "data": {
    "score": 100,
    "hacking_event": "",
    "detail_list": [
      "Malicious Address",
      "Involved Theft Activity"
    ],
    "risk_level": "Severe",
    "risk_detail": [
      {
        "entity": "Theft",
        "volume": 0,
        "percent": 100,
        "risk_type": "illicit_activity",
        "hop_num": 1,
        "exposure_type": "direct"
      }
    ],
    "address_label": "hyperunit.xyz",
    "risk_report_url": "https://light.misttrack.io/riskReport/0xadaf27611952c35de3ac46412225bc8cec66e2b6?token=8baa8563-1811-4b26-913b-337b696116ac"
  }
}
```

### 2. Create Risk Score Task

Creates a sandbox async task. In sandbox mode, known cases return `has_result: true` immediately.

```shell
POST https://sandbox-api.misttrack.io/v3/risk_score_create_task
```

#### Request Header

| Header       | Value            |
| ------------ | ---------------- |
| Content-Type | application/json |

#### Request Body

<table><thead><tr><th width="118.99609375">Parameter</th><th width="97.953125">Type</th><th width="123.19921875">Required</th><th>Description</th></tr></thead><tbody><tr><td>coin</td><td>string</td><td>yes</td><td>Supported values: <code>ETH</code>, <code>TRX</code>.</td></tr><tr><td>address</td><td>string</td><td>conditional</td><td>Sandbox address to query. Required when <code>txid</code> is empty.</td></tr><tr><td>txid</td><td>string</td><td>conditional</td><td>Sandbox transaction hash to query. Required when <code>address</code> is empty.</td></tr><tr><td>direction</td><td>string</td><td>no</td><td>Optional for transaction hash tasks. Default: <code>deposit</code>.</td></tr><tr><td>api_key</td><td>string</td><td>yes</td><td>Sandbox API key.</td></tr></tbody></table>

#### Request Example

```shell
curl --location 'https://sandbox-api.misttrack.io/v3/risk_score_create_task' \
  --header 'Content-Type: application/json' \
  --data '{
    "coin": "TRX",
    "address": "TEvwn7VF4KWfWfUSKipy6mFgjxPREPwFk2",
    "api_key": "YourApiKey"
  }'
```

#### Response Example

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

### 3. Query Risk Score Task

Retrieves the result of a sandbox task by `task_id`.

```shell
GET https://sandbox-api.misttrack.io/v3/risk_score_query_task
```

#### Query Parameters

<table><thead><tr><th width="120.24609375">Parameter</th><th width="102.35546875">Type</th><th width="109">Required</th><th>Description</th></tr></thead><tbody><tr><td>task_id</td><td>string</td><td>yes</td><td>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>Sandbox API key.</td></tr></tbody></table>

#### Request Example

```shell
curl --location 'https://sandbox-api.misttrack.io/v3/risk_score_query_task?task_id=fb4446aadfe0c2daf2181306c2f4434e78842b22a3a2dbfb3c2095331ade2cfc&api_key=YourApiKey'
```

#### Response

The response format is the same as `/v3/risk_score`.

### Response Fields

<table><thead><tr><th width="192.78125">Parameter</th><th width="106.86328125">Type</th><th>Description</th></tr></thead><tbody><tr><td>success</td><td>bool</td><td>Whether the request succeeded.</td></tr><tr><td>msg</td><td>string</td><td>Empty on success. Contains an error code on failure.</td></tr><tr><td>data.score</td><td>int</td><td>Risk score.</td></tr><tr><td>data.hacking_event</td><td>string</td><td>Related security event or incident name.</td></tr><tr><td>data.detail_list</td><td>list</td><td>Risk descriptions.</td></tr><tr><td>data.risk_level</td><td>string</td><td>Risk level: <code>Low</code>, <code>Moderate</code>, <code>High</code>, or <code>Severe</code>.</td></tr><tr><td>data.risk_detail</td><td>list</td><td>Risk calculation details.</td></tr><tr><td>data.address_label</td><td>string</td><td>Address label. Empty string means no label.</td></tr><tr><td>data.risk_report_url</td><td>string</td><td>MistTrack risk report URL.</td></tr></tbody></table>

#### `risk_detail` Fields

<table><thead><tr><th width="172.890625">Parameter</th><th width="120.5078125">Type</th><th>Description</th></tr></thead><tbody><tr><td>entity</td><td>string</td><td>Risk entity name.</td></tr><tr><td>risk_type</td><td>string</td><td>Risk type, for example <code>illicit_activity</code> or <code>risk_exchange</code>.</td></tr><tr><td>volume</td><td>float</td><td>Transaction amount related to the risk entity.</td></tr><tr><td>percent</td><td>float</td><td>Percentage of total transaction amount.</td></tr><tr><td>hop_num</td><td>int</td><td>Hop count to the risk entity.</td></tr><tr><td>exposure_type</td><td>string</td><td><code>direct</code> or <code>indirect</code>.</td></tr><tr><td>hop_dic</td><td>object</td><td>Path details by hop. This field is only present for some indirect cases.</td></tr></tbody></table>

### Error Responses

<table><thead><tr><th width="129.6796875">HTTP Status</th><th>Response</th><th>Meaning</th></tr></thead><tbody><tr><td>400</td><td><code>{"success": false, "msg": "InvalidApiKey"}</code></td><td>Missing or invalid API key.</td></tr><tr><td>400</td><td><code>{"success": false, "msg": "InvalidParameter"}</code></td><td>Unsupported <code>coin</code>, unknown sandbox target, mismatched <code>coin</code> and target, or invalid parameter.</td></tr><tr><td>400</td><td><code>{"success": false, "msg": "InvalidAddress"}</code></td><td>Both <code>address</code> and <code>txid</code> are empty.</td></tr><tr><td>429</td><td><code>{"success": false, "msg": "ExceededRateLimit", "retry_after": 1}</code></td><td>Per-second rate limit exceeded.</td></tr><tr><td>429</td><td><code>{"success": false, "msg": "ExceededDailyRateLimit", "retry_after": 123}</code></td><td>Daily rate limit exceeded.</td></tr><tr><td>200</td><td><code>{"success": false, "msg": "TaskNotFound"}</code></td><td>Invalid task id or unsupported task target.</td></tr></tbody></table>

### Available Sandbox Targets

Use the `coin` value shown in the table when requesting each target.

<table><thead><tr><th width="84.125">Coin</th><th width="90.625">Type</th><th width="179.43359375">Target</th><th width="108.5">Risk Level</th><th width="89.87890625">Score</th><th>Detail List</th></tr></thead><tbody><tr><td>ETH</td><td>address</td><td><code>0xadaf27611952c35de3ac46412225bc8cec66e2b6</code></td><td>Severe</td><td>100</td><td>Malicious Address, Involved Theft Activity</td></tr><tr><td>ETH</td><td>address</td><td><code>0xa7cbb8fbc7a1339d1e8001f1c40491f4512547ec</code></td><td>High</td><td>85</td><td>Suspected Malicious Address, Involved Theft Activity</td></tr><tr><td>ETH</td><td>address</td><td><code>0xfc1c828f44a907f8b5807b1ca4576629abc152f1</code></td><td>Moderate</td><td>34</td><td>Involved Illicit Activity, Interact With Medium-risk Tag Addresses</td></tr><tr><td>ETH</td><td>address</td><td><code>0x2ae2182f745b10ab9c11ddaace4028930cc63e93</code></td><td>Low</td><td>3</td><td>-</td></tr><tr><td>ETH</td><td>txid</td><td><code>0x49a063b6f1c624f1c914241af8ecd1237fc09104987ea9c904eebfee74787a0b</code></td><td>Severe</td><td>96</td><td>Involved Illicit Activity</td></tr><tr><td>TRX</td><td>address</td><td><code>TGJ6QtCbQXo8Q5EAaJm3944B6MTpEvbwTB</code></td><td>Severe</td><td>100</td><td>Malicious Address, Involved Theft Activity</td></tr><tr><td>TRX</td><td>address</td><td><code>TEvwn7VF4KWfWfUSKipy6mFgjxPREPwFk2</code></td><td>High</td><td>89</td><td>Involved Illicit Activity</td></tr><tr><td>TRX</td><td>address</td><td><code>TQp6K2nHpqdk5d6q8VjAYLvp1ufUKVpsts</code></td><td>Moderate</td><td>69</td><td>Involved Illicit Activity</td></tr><tr><td>TRX</td><td>address</td><td><code>TBTwgFxL4KwAzQmMAS2L13YHy58DW6zq7e</code></td><td>Low</td><td>3</td><td>Involved Illicit Activity</td></tr><tr><td>TRX</td><td>txid</td><td><code>3aa550c861c47bd955634126072e460965267ef424e4088a68d9c5368e03d789</code></td><td>Moderate</td><td>49</td><td>Involved Illicit Activity, Interact With High-risk Tag Address, Interact With Medium-risk Tag Addresses</td></tr></tbody></table>