本文介绍在 Hashgraph JS SDK 中 TokenBalanceMap.tokens 已弃用（v2.31.0+）后，推荐通过 Hedera Mirror Node REST API 安全、可靠地查询账户是否已关联某 HTS 代币，并说明零余额关联的语义含义。
本文介绍在 hashgraph js sdk 中 `tokenbalancemap.tokens` 已弃用（v2.31.0+）后，推荐通过 hedera mirror node rest api 安全、可靠地查询账户是否已关联某 hts 代币，并说明零余额关联的语义含义。
在 Hedera 网络中，“账户是否关联某 HTS 代币”与“账户是否持有该代币余额”是两个不同概念：即使账户尚未收到任何代币，只要执行过 TokenAssociateTransaction，该代币即被标记为“已关联”，且其初始余额为 0。而 SDK 中旧版 AccountBalanceQuery 的 .tokens 属性已被弃用（自 v2.31.0 起），官方明确推荐使用 Hedera Mirror Node REST API 进行此类元数据查询。
✅ 推荐方案：通过 Mirror Node 查询关联代币列表
Mirror Node 提供了实时、只读的链上状态快照。对指定账户发起 GET 请求，即可获取其全部关联代币（含 0 余额项）：
用于自动切换项目中适合的node 版本
下载
根据 package.json 中的 engines 字段自动检测 Node.js 版本需求，未安装 nvm 时自动安装并切换至对应版本。支持 Windows、macOS、Linux。适用于 Node.js 项目开发、版本切换和环境配置。
async function isAccountAssociatedWithToken(
accountId: string,
tokenId: string,
network: 'testnet' | 'mainnet' = 'testnet'
): Promise<boolean> {
const baseUrl =
network === 'testnet'
? 'https://testnet.mirrornode.hedera.com/'
: 'https://mainnet.mirrornode.hedera.com/';
try {
const response = await fetch(`${baseUrl}api/v1/accounts/${accountId}`, {
method: 'GET',
headers: { 'Content-Type': 'application/json' },
});
if (!response.ok) {
throw new Error(`HTTP ${response.status}: ${response.statusText}`);
}
const accountInfo = await response.json();
// 注意：balance.tokens 是数组，每个元素形如 { token_id: "0.0.123", balance: 0 }
const associatedTokens = Array.isArray(accountInfo.balance?.tokens)
? accountInfo.balance.tokens
: [];
return associatedTokens.some(
(t: any) => t.token_id?.toString() === tokenId.toString()
);
} catch (error) {
console.error('Failed to fetch account tokens:', error);
throw error;
}
}
// 使用示例
const accountId = '0.0.123456';
const tokenId = '0.0.789012';
isAccountAssociatedWithToken(accountId, tokenId)
.then(associated => {
console.log(`Account ${accountId} is ${associated ? '' : 'not '}associated with token ${tokenId}`);
});</boolean>
⚠️ 注意事项
- 关联 ≠ 持有：返回 true 仅表示该账户已成功执行 TokenAssociateTransaction，不保证余额大于零；需单独调用 TokenBalanceQuery（仍可用）或检查 balance 字段确认实际余额。
- 网络一致性：确保 Mirror Node 的网络环境（testnet/mainnet）与目标 accountId 和 tokenId 所属网络一致，否则将返回 404。
- 速率限制与重试：Mirror Node 对未认证请求有轻量级限流，生产环境建议添加指数退避重试逻辑。
- 类型安全建议：上述代码中 accountInfo.balance.tokens 类型未严格校验，实际项目中建议配合 Zod 或 TypeScript 接口定义进行响应结构验证。
? 总结
当 AccountBalanceQuery.tokens 不再可用时，转向 Mirror Node 是符合 Hedera 最佳实践的演进路径。它不仅规避了 SDK 弃用风险，还提供了更丰富的账户上下文（如自动代币发现、关联时间戳等）。务必牢记：HTS 的“关联性”是显式链上操作的结果，而非余额推导——这是构建健壮代币管理逻辑的关键前提。
