> 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/assets-and-market-data/rates.md).

# 匯率行情

查詢幣種對 USD 的參考價格，支援最新價格、指定時點價格與歷史價格序列。回應包含在 { data, meta } 信封。

## 最新 / 指定時點查價

可一次查詢多個幣種；未帶 at 時回傳最新價格，帶 at 時回傳該時間點之前最近一筆價格。

```bash
# 最新價（多幣）
curl "https://api.blockchainsecurity.asia/v1/rates?symbols=BTC,ETH" \
  -H "X-API-Key: ak_live_YOUR_KEY"

# 某時點（unix 秒）
curl "https://api.blockchainsecurity.asia/v1/rates?symbols=BTC,ETH&at=1700000000" \
  -H "X-API-Key: ak_live_YOUR_KEY"
```

| 參數        | 必填 | 說明                      |
| --------- | -- | ----------------------- |
| `symbols` | 是  | 逗號分隔幣種（如 `BTC,ETH`）     |
| `at`      | 否  | 指定查價時間，Unix 秒；省略時回傳最新價格 |

```json
{
  "data": {
    "at": 1700000000,
    "rates": [
      { "symbol": "BTC", "price_usd": 37500.5, "ts": 1699999200 },
      { "symbol": "ETH", "price_usd": 2050.5,  "ts": 1699999200 }
    ]
  },
  "meta": { "request_id": "..." }
}
```

> 指定 at 時，系統回傳該時間點之前最近一筆可用價格，並在 ts 標示該筆價格的實際時間。此端點免費，不扣 credit。

## 歷史序列

查詢單一幣種在指定時間區間內的 USD 歷史價格序列。成功扣除 5 credits。

```bash
curl "https://api.blockchainsecurity.asia/v1/rates/history?symbol=BTC&start=1700000000&end=1700086400" \
  -H "X-API-Key: ak_live_YOUR_KEY"
```

```json
{
  "data": {
    "symbol": "BTC",
    "points": [
      { "ts": 1700000000, "price_usd": 37500.5 },
      { "ts": 1700003600, "price_usd": 37520.1 }
    ]
  },
  "meta": { "request_id": "..." }
}
```

成功扣 **5 credit**。

## 支援幣種列表

查詢目前可回傳 USD 價格資料的幣種清單。此端點免費，不扣 credit。

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

```json
{ "data": { "symbols": ["BTC","ETH","TRX","BNB","AVAX","MATIC"] }, "meta": { "request_id": "..." } }
```

**免費（0 credit）**。

## 端點與計費

| Method | 路徑                                      | 說明            | Credit |
| ------ | --------------------------------------- | ------------- | ------ |
| `GET`  | `/v1/rates?symbols=&at=`                | 最新 / 指定時點價格查詢 | 0      |
| `GET`  | `/v1/rates/history?symbol=&start=&end=` | 歷史價格序列        | 5      |
| `GET`  | `/v1/rates/symbols`                     | 支援幣種列表        | 0      |