> For the complete documentation index, see [llms.txt](https://docs.blockchainsecurity.asia/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blockchainsecurity.asia/documentation/risk-and-intelligence/address-risk.md).

# 地址風險評分

對單一地址進行歷史交易行為分析，偵測快速進出、分散轉出、一次性錢包、分層歸集與中轉型資金流等可疑行為，並加權產出風險分數與風險等級。

目前支援 `ethereum` 與 `tron`。

## 評估風險

```bash
curl -X POST "https://api.blockchainsecurity.asia/v1/address-risk" \
  -H "X-API-Key: ak_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "blockchain": "tron",
    "address": "TMuA6YqfCeX8EhbfYEg5y7S4DqzSJireY9"
  }'
```

{% hint style="warning" %}
本端點會掃描地址的完整歷史。交易量極大的地址（如交易所熱錢包）可能因上游查詢資源上限回傳 5xx，建議此類地址改用[地址標籤](/documentation/risk-and-intelligence/labels.md)判別身分。
{% endhint %}

請求 body：

| 欄位           | 必填 | 說明                                            |
| ------------ | -- | --------------------------------------------- |
| `blockchain` | 是  | 鏈別，目前僅 `ethereum` / `tron`                    |
| `address`    | 是  | 要評估的地址                                        |
| `symbols`    | 否  | 納入評估的幣種 symbol 清單；省略時自動採用原生幣與主要穩定幣            |
| `contracts`  | 否  | contract-first：以合約位址指定幣種（與 `symbols` 二擇一，較防偽） |

```json
{
  "data": {
    "chain": "tron",
    "address": "TMuA6YqfCeX8EhbfYEg5y7S4DqzSJireY9",
    "risk_score": 26.78,
    "risk_level": "low",
    "risk_level_zh": "低",
    "behaviors": [
      {
        "code": "rapid_in_out",
        "name_zh": "快速進出",
        "severity": "high",
        "score": 12.0,
        "base_weight": 30.0,
        "intensity": 1.0,
        "recency_weight": 0.4,
        "occurrence_count": 8,
        "first_detected_at": 1584086703,
        "last_detected_at": 1638244803,
        "ever_detected": true,
        "evidence": {
          "in_amount_usd": 3412848.81,
          "out_amount_usd": 616634422.08,
          "out_ratio": 9.99,
          "window_minutes": 30
        }
      }
    ],
    "score_breakdown": {
      "rapid_in_out": 12.0,
      "burner_wallet": 8.0,
      "pass_through": 6.78,
      "total_raw": 26.78,
      "capped_total": 26.78
    },
    "evaluated_behaviors": ["rapid_in_out", "burner_wallet"],
    "deferred_behaviors": ["drainer_pattern", "risky_contract_interaction"],
    "data_window": { "from": 1533891705, "to": 1764517689, "tx_count": 1132 }
  },
  "meta": { "request_id": "..." }
}
```

| 欄位                             | 說明                                                                          |
| ------------------------------ | --------------------------------------------------------------------------- |
| `risk_score`                   | 綜合風險分數（0–100，越高越可疑）                                                         |
| `risk_level` / `risk_level_zh` | 風險等級：`low` / `medium` / `high`（附中文）                                         |
| `behaviors`                    | 觸發的可疑行為清單                                                                   |
| `behaviors[].code`             | 行為代碼（如 `rapid_in_out`、`burner_wallet`、`pass_through`、`layered_aggregation`） |
| `behaviors[].score`            | 該行為的加權後分數（`base_weight` × `intensity` × `recency_weight`）                   |
| `behaviors[].evidence`         | 觸發該行為的量化證據（金額、比例、時間窗等，依行為而異）                                                |
| `behaviors[].occurrence_count` | 歷史上偵測到的次數，`first/last_detected_at` 為首末次時間                                   |
| `score_breakdown`              | 各行為分數與加總（`capped_total` 為封頂後總分）                                             |
| `evaluated_behaviors`          | 本次已評估的行為偵測器                                                                 |
| `deferred_behaviors`           | 本次未評估（延後）的偵測器                                                               |
| `data_window`                  | 分析涵蓋的時間範圍與交易筆數                                                              |

> 較舊的行為會依時間遞減權重，因此分數反映的是加權後的整體歷史風險，而非單一事件判斷。

## 端點與計費

| Method | 路徑                 | 說明          | Credit |
| ------ | ------------------ | ----------- | ------ |
| `POST` | `/v1/address-risk` | 地址風險評分與行為分析 | 5      |