# 端點總覽

下表彙整所有端點與 credit 成本。完整的請求／回應結構、可線上試打的介面，請見互動式 API 文件。

{% hint style="success" %}
**互動式文件：** 造訪 [`/docs`](https://api.atlantis.example/docs) 可瀏覽並直接試打所有端點（已內建範例）；原始 OpenAPI 規格在 [`/api-docs/openapi.json`](https://api.atlantis.example/api-docs/openapi.json)。
{% endhint %}

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

## 幣種與鏈

詳見[幣種與鏈](/documentation/zi-liao-api/assets.md)。

| Method | 路徑                  | 說明                | Credit |
| ------ | ------------------- | ----------------- | ------ |
| `GET`  | `/v1/chains`        | 支援的鏈與幣種           | 0      |
| `GET`  | `/v1/registry`      | 完整 token registry | 0      |
| `GET`  | `/v1/assets?chain=` | 某鏈的代幣             | 0      |
| `POST` | `/v1/resolve`       | symbol／合約 → 資產規格  | 0      |

## 地址活動

詳見[地址活動](/documentation/zi-liao-api/address-activity.md)。

| Method | 路徑                                  | 說明      | Credit |
| ------ | ----------------------------------- | ------- | ------ |
| `POST` | `/v1/transactions`                  | 交易列表    | 5      |
| `POST` | `/v1/counterparty`                  | 交易對手排行  | 5      |
| `POST` | `/v1/counterparty/transfer-between` | 兩地址交易明細 | 5      |
| `POST` | `/v1/counterparty/overview`         | 兩地址聚合統計 | 5      |
| `POST` | `/v1/balance-history`               | 每日歷史餘額  | 5      |
| `POST` | `/v1/wallet-overview`               | 地址總覽    | 5      |

## Token 持有結構

詳見[持有者與集中度](/documentation/zi-liao-api/token-holders.md)。**較重的查詢，credit 權重較高。**

| Method | 路徑                        | 說明                        | Credit |
| ------ | ------------------------- | ------------------------- | ------ |
| `GET`  | `/v1/token/holders`       | 持有者排行                     | 10     |
| `GET`  | `/v1/token/concentration` | 持有集中度（HHI / Gini / Top-N） | 15     |

## 地址標籤 / 搜尋

詳見[地址標籤](/documentation/zi-liao-api/labels.md)、[地址搜尋](/documentation/zi-liao-api/search.md)。

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

## 匯率行情

詳見[匯率行情](/documentation/zi-liao-api/rates.md)。

| Method | 路徑                                      | 說明            | Credit |
| ------ | --------------------------------------- | ------------- | ------ |
| `GET`  | `/v1/rates?symbols=&at=`                | 時點 / 最新查價（批次） | 0      |
| `GET`  | `/v1/rates/history?symbol=&start=&end=` | 歷史價序列         | 5      |
| `GET`  | `/v1/rates/symbols`                     | 有資料的幣種        | 0      |

## 即時推送

詳見 [Webhook 訂閱](/documentation/cao-zuo-zhi-nan/webhooks.md)、[即時串流](/documentation/cao-zuo-zhi-nan/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      |

## 系統端點（免認證）

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

## 控制平面（需管理員 session）

管理員以帳號密碼登入，詳見[管理後台](/documentation/cao-zuo-zhi-nan/admin-console.md)。

| Method         | 路徑                                | 說明            |
| -------------- | --------------------------------- | ------------- |
| `POST`         | `/admin/api/login`                | 登入            |
| `POST`         | `/admin/api/logout`               | 登出            |
| `GET`          | `/admin/api/me`                   | 目前管理員資訊       |
| `GET` / `POST` | `/admin/api/api-keys`             | 列出／建立 API key |
| `POST`         | `/admin/api/api-keys/{id}/revoke` | 撤銷 API key    |
| `POST`         | `/admin/api/api-keys/{id}/credit` | 調整 credit 餘額  |
| `GET` / `POST` | `/admin/api/plans`                | 列出／建立方案       |

## 共通約定

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.blockchainsecurity.asia/documentation/api-can-kao/endpoints.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.