> 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/api-can-kao/endpoints.md).

# 端點總覽

本頁彙整主要端點、用途與 Credit 成本。完整請求格式、回應範例與線上試打介面，請參考互動式 API 文件。

{% hint style="success" %}
互動式 API 文件：可至 /docs 瀏覽並測試端點；原始 OpenAPI 規格位於 /api-docs/openapi.json。
{% endhint %}

所有資料平面端點需在 header 帶 `X-API-Key`，回應為 `{ data, meta }` 信封。成功（2xx）才扣 Credit。

## Assets & Market Data（資產與行情）

詳見[幣種與鏈](/documentation/assets-and-market-data/assets.md)、[匯率行情](/documentation/assets-and-market-data/rates.md)。

| Method | 路徑                                      | 說明                | Credit |
| ------ | --------------------------------------- | ----------------- | ------ |
| `GET`  | `/v1/chains`                            | 支援的鏈與幣種           | 0      |
| `GET`  | `/v1/registry`                          | 完整 token registry | 0      |
| `GET`  | `/v1/assets?chain=`                     | 某鏈的代幣             | 0      |
| `POST` | `/v1/resolve`                           | symbol／合約 → 資產規格  | 0      |
| `GET`  | `/v1/rates?symbols=&at=`                | 時點 / 最新查價（批次）     | 0      |
| `GET`  | `/v1/rates/history?symbol=&start=&end=` | 歷史價序列             | 5      |
| `GET`  | `/v1/rates/symbols`                     | 有資料的幣種            | 0      |

## On-chain Data（鏈上數據）

詳見[地址活動](/documentation/on-chain-data/address-activity.md)、[持有者與集中度](/documentation/on-chain-data/token-holders.md)。持有者與集中度是較重的查詢，Credit 權重較高。

| Method | 路徑                                  | 說明                        | Credit |
| ------ | ----------------------------------- | ------------------------- | ------ |
| `POST` | `/v1/transactions`                  | 交易列表                      | 5      |
| `GET`  | `/v1/transaction/{hash}`            | 單筆交易完整明細                  | 0      |
| `POST` | `/v1/counterparty`                  | 交易對手排行                    | 5      |
| `POST` | `/v1/counterparty/transfer-between` | 兩地址交易明細                   | 5      |
| `POST` | `/v1/counterparty/overview`         | 兩地址聚合統計                   | 5      |
| `GET`  | `/v2/counterparty/list`             | 交易對手清單（Bitcoin 加速版）       | 5      |
| `POST` | `/v1/balance-history`               | 每日歷史餘額                    | 5      |
| `POST` | `/v1/wallet-overview`               | 地址總覽                      | 5      |
| `GET`  | `/v1/token/holders`                 | 持有者排行                     | 10     |
| `GET`  | `/v1/token/concentration`           | 持有集中度（HHI / Gini / Top-N） | 15     |
| `GET`  | `/v1/token/addresses_flow`          | 多地址資金流量聚合                 | 5      |

## Risk & Intelligence（風險與情資）

詳見[地址標籤](/documentation/risk-and-intelligence/labels.md)、[地址風險](/documentation/risk-and-intelligence/address-risk.md)、[地址分類](/documentation/risk-and-intelligence/classification.md)。

| Method | 路徑                     | 說明                  | Credit |
| ------ | ---------------------- | ------------------- | ------ |
| `GET`  | `/v1/labels`           | 地址情報標籤              | 5      |
| `POST` | `/v1/address-risk`     | 行為風險評分（0–100）與可疑行為  | 5      |
| `POST` | `/v1/address-classify` | ML 地址類型分類（批次最多 100） | 5      |

## Investigation（調查追蹤）

詳見[智能追蹤](/documentation/investigation/trace.md)、[Bitcoin 分析](/documentation/investigation/bitcoin.md)。

| Method | 路徑                       | 說明                | Credit |
| ------ | ------------------------ | ----------------- | ------ |
| `POST` | `/v1/trace`              | 多跳金流路徑展開（向外 / 向內） | 5      |
| `POST` | `/v1/btc/change-address` | Bitcoin 找零地址偵測    | 5      |

## Cross-chain（跨鏈追蹤）

詳見[跨鏈追蹤](/documentation/cross-chain/cross-chain.md)。

| Method | 路徑                      | 說明       | Credit |
| ------ | ----------------------- | -------- | ------ |
| `GET`  | `/v1/cross-chain`       | 單筆交易跨鏈追蹤 | 5      |
| `POST` | `/v1/cross-chain/batch` | 批次跨鏈追蹤   | 5      |

## Address Utilities（地址工具）

詳見[地址工具](/documentation/address-utilities/search.md)。

| Method | 路徑                           | 說明        | Credit |
| ------ | ---------------------------- | --------- | ------ |
| `GET`  | `/v1/addresses/resolve`      | 地址驗證 / 糾錯 | 5      |
| `GET`  | `/v1/addresses/autocomplete` | 前綴自動完成    | 0      |

## Events（事件訂閱）

詳見 [Webhook 訂閱](/documentation/events/webhooks.md)、[即時串流](/documentation/events/streaming.md)。

| Method   | 路徑                  | 說明               | Credit |
| -------- | ------------------- | ---------------- | ------ |
| `GET`    | `/v1/webhooks`      | 列出 webhook 訂閱    | 0      |
| `POST`   | `/v1/webhooks`      | 建立 webhook 訂閱    | 0      |
| `DELETE` | `/v1/webhooks/{id}` | 刪除 webhook 訂閱    | 0      |
| `GET`    | `/v1/stream`        | WebSocket 即時事件串流 | 0      |

## System（系統端點，免認證）

| Method | 路徑                       | 說明              |
| ------ | ------------------------ | --------------- |
| `GET`  | `/healthz`               | 存活檢查（liveness）  |
| `GET`  | `/readyz`                | 就緒檢查（readiness） |
| `GET`  | `/docs`                  | 互動式 API 文件      |
| `GET`  | `/api-docs/openapi.json` | OpenAPI 規格      |

## 共通約定

| 項目   | 約定                                                 |
| ---- | -------------------------------------------------- |
| 認證   | 資料平面 `X-API-Key`                                   |
| 成功回應 | `{ data, meta }` 信封                                |
| 錯誤回應 | `{ error: { code, message } }` 信封                  |
| 計費   | 成功（2xx）才扣；回應帶 `X-Credit-Cost`、`X-Credit-Remaining` |
| 追蹤   | 回應帶 `X-Request-Id`                                 |