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

# 快速上手

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

{% hint style="success" %}
**預計時間：5 分鐘。** 你只需要一把 API key 與一個能發 HTTP 請求的工具（cURL、Postman 或任何語言的 HTTP client）。
{% endhint %}

{% hint style="info" %}
本服務之資料查詢、完整 API 模組與商用串接，均需使用有效 API Key。如需申請測試、正式試用或評估串接流程，請聯絡 <support@chainsecurity.asia> 取得 API key。
{% endhint %}

## 步驟

{% stepper %}
{% step %}

#### 取得 API key

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

```
ak_live_3f9a2c7b8e1d4a605c...
```

{% hint style="warning" %}
明碼 key **只會出現這一次**，請當場妥善保存。遺失只能撤銷後重建。
{% endhint %}
{% endstep %}

{% step %}

#### 確認連線

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

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

{% endstep %}

{% step %}

#### 發出第一個已認證的請求

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

{% tabs %}
{% tab title="cURL" %}

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

{% endtab %}

{% tab title="Python" %}

```python
import requests

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

{% endtab %}

{% tab title="JavaScript" %}

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

{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

#### 看懂回應

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

{% code title="response.json" %}

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

{% endcode %}

同時，回應 header 會帶上：

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

## 常見問題

<details>

<summary>我收到 401 unauthorized</summary>

確認 `X-API-Key` 有帶上、值正確，且該 key 尚未被撤銷或停用。詳見[認證與 API key](/documentation/kai-shi-shi-yong/authentication.md)。

</details>

<details>

<summary>我收到 402 insufficient_credit</summary>

該 key 的 Credit 餘額不足以支付本次請求。請聯絡你方管理員加值，或參考 [Credit 計費](/documentation/he-xin-gai-nian/credit-billing.md)。

</details>

<details>

<summary>我收到 429 rate_limited</summary>

觸發限流。回應的 `Retry-After` header 會告訴你建議幾秒後重試。詳見[限流](/documentation/he-xin-gai-nian/rate-limiting.md)。

</details>

## 下一步

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

{% content-ref url="/pages/IIOYHLhxhH8x5X7Vxdx1" %}
[回應格式](/documentation/he-xin-gai-nian/response-format.md)
{% endcontent-ref %}