> 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/labels.md).

# 地址標籤與身分

查詢地址在各情報來源中的標籤、分類與來源狀態，例如交易所、混幣器、詐騙、制裁或其他風險相關標籤。成功回應扣除 5 credits，結果以 { data, meta } 信封回傳。

## 查標籤

```bash
curl "https://api.blockchainsecurity.asia/v1/labels?chain=ethereum&address=0x28c6c06298d514db089934071355e5743bf21d60" \
  -H "X-API-Key: ak_live_YOUR_KEY"
```

| 參數        | 必填 | 說明                                            |
| --------- | -- | --------------------------------------------- |
| `chain`   | 是  | 鏈別（ethereum / bsc / tron / bitcoin …）         |
| `address` | 是  | 查詢地址                                          |
| `intent`  | 否  | 查詢意圖：`label`（預設）＝命中且信心足即回傳；`deep`＝所有來源照查      |
| `sources` | 否  | 來源；省略=預設來源，`all`=全部，或逗號分隔                     |
| `refresh` | 否  | 是否要求重新查詢來源；true 時會盡量跳過快取，但仍可能受來源可用性、限流或方案權限影響 |

```json
{
  "data": {
    "chain": "ethereum",
    "address": "0x28c6c06298d514db089934071355e5743bf21d60",
    "label": {
      "entity_name": "Binance",
      "category": "entity_actor",
      "labels": ["Binance", "hot"],
      "confidence": 1.0,
      "verified": true,
      "hit_tier": "first_party"
    },
    "needs_deep_analysis": false,
    "results": [
      {
        "source": "first_party",
        "status": "ok",
        "category": "entity_actor",
        "name": "Binance",
        "labels": ["Binance", "hot"],
        "verified": true,
        "raw": { "...": "原始來源回應" },
        "fetched_at": 1700000000,
        "cached": false
      }
    ],
    "fetched_at": 1700000000
  },
  "meta": { "request_id": "..." }
}
```

`data.label` 為跨來源彙整後的綜合標籤，適合直接顯示：

| 欄位            | 說明                          |
| ------------- | --------------------------- |
| `entity_name` | 實體名稱（如 Binance）             |
| `category`    | 正規化分類                       |
| `labels`      | 標籤清單                        |
| `confidence`  | 信心分數（0–1）                   |
| `verified`    | 是否經過驗證                      |
| `hit_tier`    | 命中層級（如 `first_party`＝自有情資庫） |

`data.needs_deep_analysis` 為布林值：true 表示標籤資訊不足，建議再走 `/v1/address-risk` 等深度分析。

`results` 為各來源明細陣列，每個來源同一外殼：

| 欄位         | 說明                                     |
| ---------- | -------------------------------------- |
| `source`   | 來源名稱（如 `first_party`）                  |
| `status`   | `ok` / `unknown` / `error` / `timeout` |
| `category` | 正規化分類（exchange / mixer …）              |
| `name`     | 名稱（如 Binance）                          |
| `labels`   | 標籤清單                                   |
| `verified` | 該來源結果是否經過驗證                            |
| `raw`      | raw｜來源回應摘要或原始欄位保留，實際內容依來源而定            |
| `cached`   | 是否使用快取結果                               |

## 端點與計費

| Method | 路徑           | 說明     | Credit |
| ------ | ------------ | ------ | ------ |
| `GET`  | `/v1/labels` | 地址標籤查詢 | 5      |