> 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/address-utilities/search.md).

# 地址工具

協助使用者在輸入階段就拿到正確完整的地址：`resolve` 驗證地址格式並對打錯的地址回傳相似候選，`autocomplete` 依前綴即時補全，適合搜尋框的 type-ahead 場景。

## 地址驗證 / 相似候選（resolve）

驗證一個地址是否符合指定鏈別格式；若未完全命中，可回傳相似候選。成功回應扣除 5 credits。

```bash
curl "https://api.blockchainsecurity.asia/v1/addresses/resolve?chain=tron&q=TXgXcJwxbDsDfTHq3BSZagZor4Dg74tb5Z" \
  -H "X-API-Key: ak_live_YOUR_KEY"
```

| 參數      | 必填 | 說明                                             |
| ------- | -- | ---------------------------------------------- |
| `q`     | 是  | 要驗證或修正的地址                                      |
| `chain` | 否  | 鏈別，例如 `tron`、`ethereum`、`bitcoin`；省略時僅做格式與候選推斷 |
| `limit` | 否  | 相似候選數上限                                        |

```json
{
  "data": {
    "query": "TXgXcJwxbDsDfTHq3BSZagZor4Dg74tb5Z",
    "chain": "tron",
    "match": true,
    "candidates": [],
    "total": 0,
    "took_ms": 3
  },
  "meta": { "request_id": "..." }
}
```

> match: true 表示輸入地址通過驗證或完全命中；match: false 時，candidates 會列出相似候選地址，供使用者確認是否輸入錯誤。

## 自動完成（autocomplete）

依地址前綴回傳候選清單，適合用於搜尋框自動完成。此端點不扣除 credit；q 至少 5 個字元。

```bash
curl "https://api.blockchainsecurity.asia/v1/addresses/autocomplete?chain=tron&q=TXgXcJ" \
  -H "X-API-Key: ak_live_YOUR_KEY"
```

```json
{
  "data": {
    "query": "TXgXcJ",
    "chain": "tron",
    "candidates": ["TXgXcJwxbDsDfTHq3BSZagZor4Dg74tb5Z"],
    "total": 1
  },
  "meta": { "request_id": "..." }
}
```

## 端點與計費

| Method | 路徑                           | 說明        | Credit |
| ------ | ---------------------------- | --------- | ------ |
| `GET`  | `/v1/addresses/resolve`      | 地址驗證與相似候選 | 5      |
| `GET`  | `/v1/addresses/autocomplete` | 地址前綴自動完成  | 0      |