快速上手

五分鐘內完成第一次 API 呼叫。

這份快速指南帶你用一把 API key 發出第一個請求，並看懂回應。

預計時間：5 分鐘。 你只需要一把 API key 與一個能發 HTTP 請求的工具（cURL、Postman 或任何語言的 HTTP client）。

本服務之資料查詢、完整 API 模組與商用串接，均需使用有效 API Key。如需申請測試、正式試用或評估串接流程，請聯絡 [e-mail] 取得 API key。

步驟

1

取得 API key

API key 由你方的管理員建立。建立時系統會回傳一次性的明碼 key，格式類似：

ak_live_3f9a2c7b8e1d4a605c...

明碼 key 只會出現這一次，請當場妥善保存。遺失只能撤銷後重建。

2

確認連線

先打不需認證的健康檢查端點，確認網路通暢：

curl https://api.blockchainsecurity.asia/healthz
# {"status":"ok"}

3

發出第一個已認證的請求

把你的 key 放進 X-API-Key header。以「列出 webhook 訂閱」為例：

cURL

curl https://api.blockchainsecurity.asia/v1/webhooks \
  -H "X-API-Key: ak_live_YOUR_KEY"

Python

import requests

resp = requests.get(
    "https://api.blockchainsecurity.asia/v1/webhooks",
    headers={"X-API-Key": "ak_live_YOUR_KEY"},
)
print(resp.json())

JavaScript

const resp = await fetch("https://api.blockchainsecurity.asia/v1/webhooks", {
  headers: { "X-API-Key": "ak_live_YOUR_KEY" },
});
console.log(await resp.json());

4

看懂回應

成功的回應一律包在 { data, meta } 信封內：

response.json

{
  "data": [],
  "meta": {
    "request_id": "9b1c2d3e-4f5a-6789-..."
  }
}

同時，回應 header 會帶上：

Header	意義
X-Request-Id	本次請求追蹤碼，除錯、客服與稽核時可提供
X-Credit-Cost	本次扣除的 Credit，僅成功且需計費時出現
X-Credit-Remaining	扣點後的剩餘 Credit，僅適用於 Credit 方案

常見問題

我收到 401 unauthorized

確認 X-API-Key 有帶上、值正確，且該 key 尚未被撤銷或停用。詳見認證與 API key。

我收到 402 insufficient_credit

該 key 的 Credit 餘額不足以支付本次請求。請聯絡你方管理員加值，或參考 Credit 計費。

我收到 429 rate_limited

觸發限流。回應的 Retry-After header 會告訴你建議幾秒後重試。詳見限流。

下一步

認證與 API key回應格式