如何透過錢包地址查看代幣餘額？

直接鏈特定餘額查詢

1. 使用者可以透過向/balance/{chain}/{address}提交 GET 請求來檢索代幣餘額，其中 {chain} 是支援的七個區塊鏈之一，{address} 是錢包的十六進位字串。

2. 端點傳回本機代幣餘額和 ERC-20/BEP-20/SPL 代幣持有量，取決於特定於鏈的合約標準和索引器覆蓋範圍。

3. Solana 回應包括映射到錢包的 SPL 代幣帳戶，而以太坊和 Base 透過多重呼叫聚合返回 ETH 和代幣餘額。

4. Hedera查詢僅傳回本機HBAR餘額；HTS 代幣需要此端點未涵蓋的單獨合約互動。

5. Bitcoin 回應反映基於 UTXO 的 BTC 餘額，不支援 RGB 或其他標記化層。

身份驗證要求

1. 每個餘額請求必須包含X-API-Key標頭，其中包含 AgentHustle AI 頒發的有效憑證。

2. 金鑰的範圍僅限於特定的鍊和權限－嘗試使用僅限以太坊的金鑰查詢 BSC 會導致 HTTP 403。

3. 每個金鑰適用速率限制：所有端點每分鐘 60 個請求，在 API 閘道層級強制執行。

4. 無效或過期的金鑰會觸發 HTTP 401，其中 JSON 正文指示「invalid_api_key」或「key_expired」。

5. 不涉及會話cookie或OAuth流程；身份驗證是無狀態且標頭驅動的。

響應結構和資料字段

1. 成功的回應使用 HTTP 200 並包含一個頂級餘額字段，表示為基本單位的字串化整數（例如，wei 代表 ETH，lamports 代表 SOL）。

2. tokens陣列列出了非原生資產，每個資產都有contractAddress 、 symbol 、 decimals和rawBalance 。

3.lastUpdated欄位報告 Unix 時間戳記（以毫秒為單位），與底層區塊鏈索引器的最新同步區塊對齊。

4. 對於不持有本幣以外的代幣的錢包，代幣數組仍然存在但為空。

5. 所有數值均以字串形式傳遞，以防止 JSON 序列化過程中浮點精度遺失。

ENS 名稱解析集成

1. 啟用解析器服務時，可以直接使用 ENS 名稱（例如， vitalik.eth）來取代十六進位位址。

2. API 透過以太坊主網的 ENS 註冊表自動執行反向查找，然後將查詢轉發到特定於鏈的餘額端點。

3. 如果名稱未解析為位址或指向無效的校驗和格式，則解析會自動失敗。

4. 支援的 ENS TLD 包括 .eth、.xyz 和 .luxe；除非在 ENS 相容的解析器中註冊，否則不會處理 .com 和 .org。

5. PayPal 和 Venmo 整合允許使用 ENS 名稱進行 PYUSD 轉賬，但餘額檢查仍然是鏈本機的，並且不反映鏈外支付餘額。

常見問題解答

Q：我可以檢查 Cardano 或 Avalanche 等不受支援的鏈上的錢包餘額嗎？答：不可以。此端點僅支援 Solana、Ethereum、Base、BSC、Polygon、Hedera 和 Bitcoin。對其他鏈的請求回傳 HTTP 400，錯​​誤代碼為「unsupported_chain」。

Q：API 是否可以偵測以太幣錢包中的 wBTC 或 wETH 等打包代幣？答：是的。符合 ERC-20 標準的包裝代幣會出現在代幣數組中，並帶有正確的符號、小數點和原始餘額。

Q：如果錢包所有資產餘額為零，會發生什麼事？答：回應包括餘額：'0'和一個空的令牌數組。 HTTP 狀態仍為 200。

Q：有沒有辦法在一個請求中批次檢查多個位址？答： 不是原生的。每個位址都需要一個單獨的 HTTP 請求。客戶端必須在外部實作並行化或排隊邏輯。