交易所钱包集成

本文是交易所、托管钱包及加密支付平台接入 TRON 网络的实现指南。内容涵盖两种接入路线（TronGrid 与自建全节点）、核心业务接口（余额查询、转账、交易历史）、基于区块解析的充值检测，以及 Stake 2.0 质押 API 对接。

关于架构设计的总体评估与上线前核对清单，请参阅交易所与托管钱包集成。

📘

前置阅读

• 账户
• 交易

---

1. 接入层技术选型

开发团队通常可以选择以下两条对接路径：

• 直接对接 TronGrid：使用常见托管节点服务，开发周期短，但会受到套餐限流影响。
• 部署自建全节点：访问速率不受外部服务限制，数据自主度最高，但需要自行负责服务器和日常运维。

如果平台尚未决定接入方案，先读交易所与托管钱包集成 § 2的架构对比。切换同一类接口的接入方时，业务代码通常只需要调整 Base URL；但 JSON-RPC 与节点 HTTP API 的请求和响应格式不同，不能直接混用。

这两条路径也可以在生产环境共存：许多机构在处理核心高频业务（如提现广播、区块扫描）时使用自建的全节点；而同时将非核心、低频次的数据查询（如账户转账流水历史、合约事件）分流至 TronGrid 扩展接口。

---

2. 部署自建全节点

2.1 部署全节点

关于节点服务器的硬件配置与基础安装流程，请参阅部署节点。

2.2 针对交易所业务的节点配置

在 config.conf 中，以下三个配置项直接影响交易所充提币业务：

📘

什么是合约内部交易 (Internal Transaction)

当智能合约在执行中调用另一份合约，或者通过合约代码向外部账户转移 TRX 或 TRC-10 资产时，这些动作不会以顶层独立交易（Top-level Transaction）形式出现在区块中，而是记录在主交易执行轨迹的内部交易里。

如果充值扫描程序只检查区块中的顶层交易，用户通过兑换协议或批量分发合约向充值钱包入账时，资金流会被遗漏。将 vm.saveInternalTx 设置为 true 后，这类内部交易才能被正常查询。

其他通用的全节点配置说明，请参阅部署节点。

---

3. 使用 TronGrid 托管服务

TronGrid 是常用的节点托管平台。它开放标准全节点 HTTP 和 gRPC 接口，并提供一组扩展 API，例如预索引的账户交易历史、TRC-20 转账历史和智能合约事件。

3.1 接入端点（Endpoint）列表

3.2 鉴权 API Key 与限流限制

生产环境高频访问需要在 HTTP 请求头中附加 TRON-PRO-API-KEY。API key 创建与请求头格式见 API Key；请求配额、429 / 403 响应和退避策略见 TronGrid 速率限制。限流策略可能调整，不要把具体频次硬编码进运维预案。

3.3 常用扩展 API 接口

除标准 RPC endpoint 外，TronGrid 还提供以下预索引接口，无需自行解析区块：

完整的接口规范请参考 TronGrid V1 API 概览。

---

4. 交易所核心业务接口

以下接口适用于上述两种接入路径。使用 TronGrid 时，在接口路径前拼接对应 Base URL；使用自建全节点时，使用节点监听地址（主网默认 HTTP 端口为 http://127.0.0.1:8090）。

4.1 账户余额查询

注：TRC-20 余额查询本质上是向 Token 合约发起 balanceOf(address) 的只读模拟调用。使用自建全节点时，请确保已按第 2.2 节启用 vm.supportConstant = true。

4.2 提现交易广播

发起一笔链上转账需要经过：离线交易构造、本地私钥签名以及网络广播三步。详细的交易周期与开发建议，请查阅交易底册。包括 JavaScript (TronWeb)、Java (Trident) 及 Go (gotron-sdk) 等各语言 SDK 均内置了完善的离线签名适配库。

注：TRC-20 及所有智能合约提现交易都需要配置合理的 fee_limit。它限制本次交易可使用的能量上限，覆盖质押能量和燃烧 TRX 可换算出的能量。详情请参阅资源模型。

4.3 检索交易历史流水（仅 TronGrid 路线支持）

标准自建只读全节点不提供“按指定地址直接拉取历史交易”的 API endpoint。若需要快速获取某一账户的交易账单，可以按第 5 节自行解析区块入库，也可以调用 TronGrid 的预索引扩展接口：

---

5. 基于区块扫描的充值监听机制

部署自建节点的平台，最稳妥的充值监听方案是由后台进程持续扫描最新已固化区块，并按交易类型分发到对应记账逻辑。

5.1 推荐区块解析流程

1. 轮询固化高度：定时调用 /walletsolidity/getnowblock（GetNowBlock，SolidityNode）接口，获取当前最新的已固化区块高度。
2. 拉取区块详情：每当检测到有新区块固化，调用 /walletsolidity/getblockbynum（GetBlockByNum，SolidityNode）接口，按区块高度拉取该区块的完整明细数据。
3. 遍历交易并分发：逐个读取区块内每笔交易的类型字段 raw_data.contract[0].type，并路由至对应的处理逻辑。
4. 解析合约交易：若交易类型涉及智能合约调用，除检查交易状态外，还需进一步检索交易收据日志以及内部交易列表（详见下述）。

⚠️

安全警告：请务必基于已固化区块（Solidified Block）进行入账检测

固化高度通常比最新链头滞后约 1 分钟。区块之后有至少 19 位不同 SR 在该区块高度及以上产块后，该区块进入固化状态。基于固化区块解析入账，可以避免临时分叉导致的“假充值”。固化原理见区块固化机制。

5.2 合约类型分发对照表

在分析区块内交易的 contract[0].type 时，以下三类合约涉及资金转移，是需要处理的核心类型：

5.3 关于 TRC-10 Token 的 ID 解析适配

在解析 TRC-10 交易（TransferAssetContract）时，asset_name 字段所携带的内容因交易发生的时间（即所在区块高度）不同而有两种表现形式：

📘

为什么底层数据结构存在此种历史差异

在 TRON 网络早期，系统限制每个 TRC-10 资产的英文缩写名必须保持全网唯一，因此可以使用其名称字符串直接作为唯一标识。

随着生态发展，为了让 Token 命名更加自由灵活，TRON 委员会通过并激活了 14 号治理提议，允许创建同名但数字 ID 不同的 TRC-10 资产。自该提议激活（区块高度 5537806）之后，只有全局分配的数字 ID 能作为资产的唯一标识符。

交易所适配预案：

• 绝大多数交易所与新对接钱包只需要监听未来的充值充币行为，可以直接将 asset_name 视作数字 ID 进行匹配入账，并忽略高度 5537806 之前的极早期历史转账。
• 区块浏览器与全历史索引器则必须以高度 5537806 为界，在解析时执行分支适配：对于早期区块根据名称字符串执行反向查找，对近期区块则根据数字 ID 进行匹配。

5.4 智能合约调用的解析步骤（TRC-20 与内部交易检测）

单笔类型为 TriggerSmartContract 的交易可能会在底层同时触发多笔 TRC-20 转账、TRX 或 TRC-10 的内部交易。请严格按照以下步骤遍历并解析，以防漏账：

1. 确认交易执行状态：调用 /walletsolidity/gettransactioninfobyid（GetTransactionInfoById，SolidityNode）获取交易收据，核实 receipt.result 是否为 SUCCESS。执行失败的交易应直接跳过。
2. 解析 TRC-20 充值转账：遍历交易收据中的事件日志 log[] 数组。寻找标准 Transfer(address,address,uint256) 事件记录，即 topics[0] 等于 ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef。解析合约地址、发送方、接收方和转账金额，并核对接收方是否为平台充值账户。日志解析规则见事件日志解码规范。
3. 解析内部交易充值：遍历交易信息中的内部交易列表 internal_transactions[] 数组。对每条记录进行如下核对：
   • 若 callValueInfo[0].tokenId 为空且 callValue 大于 0，说明这是一笔通过合约派生并发生的 TRX 转账。请记录并检查其中的发送方 caller、接收方 transferTo_address 及转账数量 callValue（单位为 sun）。
   • 若 callValueInfo[i].tokenId 不为空，说明这是一笔由合约触发的 TRC-10 资产转账。请读取对应的发送方 caller、接收方 transferTo_address、资产标识数字 ID tokenId 以及数量 callValue。

相关内部交易的数据结构定义，可参考以下测试网样例回执：

• 包含 TRX 内部交易的样例回执
• 包含 TRC-10 内部交易的样例回执

---

6. 对接质押业务 (Stake 2.0)

如果平台向用户提供 TRX 质押服务，需要实现 Stake 2.0 API。早期使用旧规则质押的存量资产仍可使用旧解除质押 API；新的质押流程应统一使用 Stake 2.0。锁定期、资源委派和 SR 投票规则见质押、投票与奖励机制。

6.1 质押与本金赎回 API

⚠️

关键交互：解除质押锁定期提示

用户调用 /wallet/unfreezebalancev2 解除质押后，到调用 /wallet/withdrawexpireunfreeze 取回资金前，这部分 TRX 处于等待提取状态。

等待天数由链参数 UNFREEZE_DELAY_DAYS（参数 ID 70）控制。主网当前值为 14 天，但不同测试网或未来治理调整后可能不同。

客户端 UI 应动态展示等待期，不要硬编码 14 天。推荐做法是在用户发起解除质押时，通过 /wallet/getchainparameters 查询并计算，展示“资金预计可于 YYYY-MM-DD 提取”。

6.2 资源委派（代理）API

通过 Stake 2.0 质押后，平台可以将获得的带宽或能量委派给名下充值钱包，以降低充提币资源成本：

6.3 投票选举与奖励提取 API

6.4 查询质押状态与统计

---

相关资源

• 交易所接入方案概述 —— 整体技术架构与上线前安全检查清单
• 钱包开发者指南 —— 非托管钱包的密钥管理与签名构建
• 部署节点 —— 自建全节点教程
• TronGrid —— TronGrid 节点服务和扩展 API 介绍
• TronGrid V1 API 概览 —— 账户历史、TRC-20 转账、事件日志和内部交易查询
• API Key —— 创建 API key、选择网络入口和配置请求头
• 资源模型 —— 理解带宽、能量及 fee_limit
• 质押、投票与奖励 —— 质押、投票与奖励机制
• 共识与 DPoS 机制 —— 区块产生与最终性确认
• 常见问题 FAQ —— 智能合约调用、能量不足等常见问题排查