如何通过钱包地址查看代币余额？

直接链特定余额查询

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 转账，但余额检查仍然是链本机的，并且不反映链外支付余额。

常见问题解答

问：我可以检查 Cardano 或 Avalanche 等不受支持的链上的钱包余额吗？答：不可以。该端点仅支持 Solana、Ethereum、Base、BSC、Polygon、Hedera 和 Bitcoin。对其他链的请求返回 HTTP 400，错误代码为“unsupported_chain”。

问：API 是否可以检测以太坊钱包中的 wBTC 或 wETH 等打包代币？答：是的。符合 ERC-20 标准的包装代币会出现在代币数组中，并带有正确的符号、小数点和原始余额。

问：如果钱包所有资产余额为零，会发生什么情况？答：响应包括余额：'0'和一个空的令牌数组。 HTTP 状态仍为 200。

问：有没有办法在一个请求中批量检查多个地址？答： 不是原生的。每个地址都需要一个单独的 HTTP 请求。客户端必须在外部实现并行化或排队逻辑。