> 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/kai-shi-shi-yong/overview.md).

# 服務概觀

BCS API 是一個 **API gateway**：你的應用程式只要對接這一個入口，就能存取背後的各項區塊鏈資料與情報服務。Gateway 負責處理認證、限流、計費、審計與可觀測性，讓你專注在業務本身。

## 運作方式

```
你的應用程式
    │
    │ HTTPS + X-API-Key
    ▼
BCS API
    ├─ Authentication
    ├─ Rate Limiting
    ├─ Billing
    ├─ Audit Log
    └─ Observability
    │
    ▼
各項區塊鏈服務
地址風險 / 交易行為 / 情資
```

每一次請求都會：

1. 以 `X-API-Key` 驗證身分。
2. 依「API key + 端點」做限流。
3. 呼叫對應的後端服務。
4. **成功（2xx）時**才依端點權重扣除 credit。
5. 寫入稽核紀錄，並在回應帶上 `X-Request-Id`、`X-Credit-Cost`、`X-Credit-`\
   `Remaining`。

## 你需要知道的基本約定

| 項目   | 約定                                            |
| ---- | --------------------------------------------- |
| 通訊協定 | HTTPS，REST + JSON                             |
| 認證   | 在 HTTP header 帶 `X-API-Key: <你的 key>`         |
| 成功回應 | 一律包在 `{ "data": ..., "meta": ... }` 信封內       |
| 錯誤回應 | 一律包在 `{ "error": { "code", "message" } }` 信封內 |
| 版本   | 路徑前綴 `/v1`                                    |
| 分頁   | 查詢參數 `?limit=&offset=`                        |
| 計費   | credit 制，成功才扣，回應 header 附本次成本與餘額              |

### 使用端與管理端

BCS  API 將「API 呼叫」與「帳號管理」分成兩個獨立區域：

{% tabs %}
{% tab title="API 使用端（給系統串接）" %}
API 使用端（給系統串接）

供客戶系統、後端服務、交易系統、風控系統或分析模型呼叫 API 使用，例如鏈上資料查詢、地址風險評分、資金流追蹤、交易行為分析與市場訊號查詢。

• 使用 API key 認證（X-API-Key）。\
• 依 API key、方案與 endpoint 套用限流規則。\
• 成功回應依 Credit 規則扣點。\
• 每次請求皆回傳 request\_id，方便追蹤、除錯與對帳。
{% endtab %}

{% tab title="管理後台（給管理員）" %}
管理後台（給管理員）

供管理員建立、撤銷與管理 API key，查看用量、調整 Credit 額度、管理方案與查詢審計紀錄。

• 使用帳號密碼登入，取得管理 session。\
• 不使用 API key 呼叫。\
• 管理操作不依 Credit 扣點。\
• 仍受角色權限、操作紀錄與安全性頻率限制控管。
{% endtab %}
{% endtabs %}

## 下一步

{% content-ref url="/pages/fMIKfNrelo451cfsRJe8" %}
[快速上手](/documentation/kai-shi-shi-yong/quickstart.md)
{% endcontent-ref %}

{% content-ref url="/pages/MFQ1oeKPnts4wocXInGo" %}
[認證與 API key](/documentation/kai-shi-shi-yong/authentication.md)
{% endcontent-ref %}