TRON 地址

TRC20 地址 API:生成地址并监控存款

TRC20 地址是标准的 TRON 账户地址:34 个字符的 Base58Check 形式,以 T 开头。它持有 TRX 和 USDT 等所有 TRC-20 代币。同一个地址还有以 41 开头的 42 个字符的十六进制写法。从该地址发送要消耗 Energy 和 Bandwidth,接收则免费。

7 天免费试用 — 无需信用卡,无需 KYC 即可开始 非托管 — 私钥始终由你掌控 套餐起价 49 欧元/月(490 欧元/年)— 查看套餐和速率限制

调用 POST /api/v2/tron/addresses 生成 TRC20 地址,响应是以 T 开头的 Base58Check 地址。用 POST /api/v2/tron/webhooks 注册 webhook 后,每笔 USDT-TRC20 存款都会通知你。本页依次讲格式、创建、监控和发送。

下面所有调用都发往 https://app.chaingateway.io,并在 Authorization 头中带 Bearer 令牌。给任意调用加上 X-Network: testnet,它就会转到 TRON 测试网,整个流程可以用免费的测试 TRX 演练。想看格式的详细说明,见博客上的什么是 TRC20 地址?

TRC20 地址是什么样的?

TRC20 地址是 TRON 账户地址的 Base58Check 形式,例如 TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL。它有 34 个字符,以 T 开头。TRON 的账户文档把底层的值定义为 21 字节:开头是 0x41 前缀字节,后面 20 字节与由同一公钥派生的 Ethereum 地址一致。

因此同一个地址还有一种 42 个字符、以 41 开头的十六进制写法。节点 API 常返回这种形式,而钱包和区块浏览器显示的是 Base58Check 形式。TronWeb 用 tronWeb.address.toHex() 和 fromHex() 在两者之间转换。

「TRC20」指的是代币标准,不是地址。TRC-20 是 TRON 的同质化代币标准,在接口层面与 Ethereum 的 ERC-20 兼容。一个 TRON 地址持有 TRX 和所有 TRC-20 代币。

TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL 418840E6C55B9ADA326D211D818C34A994AECED808 1 2 3 4
  1. 钱包和区块浏览器中显示的 Base58Check 形式:34 个字符,以 T 开头。
  2. 41 前缀字节表示该值是 TRON 地址。
  3. 其余 20 字节与由同一公钥派生的 Ethereum 地址相同。
  4. 十六进制形式:共 42 个字符,许多节点 API 返回这种形式。
同一个 TRON 地址的两种写法。示例取自 TRON 账户文档。

TRC20 地址与 TRC20 合约地址是同一个东西吗?

不是。钱包地址是由私钥控制的账户。合约地址属于已部署的代码,没有人持有它的密钥。TRON 文档把两者都列为账户类型,两者也都写成以 T 开头的字符串,所以字符串本身无法区分。

合约地址标识的是哪一种代币在转移,它绝不是转账的收款地址。USDT 的 TRC-20 合约是 TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t,发送到合约地址的代币在几乎所有情况下都无法找回。博客指南更详细地解释了两者的区别。

为什么新生成的 TRC20 地址在 Tronscan 上查不到?

因为 TRON 只有在账户激活之后才会识别它。按 TRON 账户文档,新生成的密钥对只存在于本地,在激活之前,无法通过 API 或区块浏览器查到这个地址。

激活的方式是:已有账户向新地址发送任意数量的 TRX 或 TRC-10 代币,并由发送方支付账户创建费。文档撰写时给出的主网创建费是 1 TRX,围绕它规划付款流程之前,请先核对当前数值。生成的地址可以用于存款和 webhook,但不要指望区块浏览器在首次激活之前显示它。

TRC20 地址接口:创建、读取、监控、发送

四类任务,以及对应的路由。创建地址和注册 webhook 完全不需要私钥,只有发送才需要。

接口作用
POST /api/v2/tron/addresses生成新的 TRON 地址
POST /api/v2/tron/addresses/import导入已有私钥,让 API 能够代表该地址签名
POST /api/v2/tron/addresses/{address}修改用于加密已存私钥的密码
DELETE /api/v2/tron/addresses/{address}从账户中移除地址
GET /api/v2/tron/balances/{address}该地址的 TRX 余额
GET /api/v2/tron/balances/{address}/trc20/{contract_address}单个 TRC-20 代币的余额,包括 USDT
GET /api/v2/tron/balances/{address}/trc10/{token_id}TRC-10 代币的余额
POST /api/v2/tron/webhooks订阅该地址的 TRX、TRC-10、TRC-20 或 TRC-721 转账
GET /api/v2/tron/webhooks/notifications列出已经送达的通知,用于对账
POST /api/v2/tron/transactions/trc20从该地址发送 USDT 等 TRC-20 代币

存款系统会用到的接口就是这些。完整的 TRON 参考共 40 个操作,包括质押和自行签名,见 TRON API 页面。webhook 上的 type 字段和单独的 /transactions/trc10 路由,是因为 TRON 同时有两套代币标准。如果你是要发行代币,而不是接收现有代币,TRC10 与 TRC20 对比说明了该选哪一套。

如何通过 REST 生成 TRC20 地址?

POST /api/v2/tron/addresses 创建一个地址。请求体只有一个可选字段 password,它决定托管模式。传入密码,私钥就用它加密保存,之后的转账用密码而不是私钥来认证。不传密码,响应会直接返回私钥,由你存入自己的保险库。API 参考明确说明密码不会被保存:密码丢了,钱包就无法恢复。换个角度说,别人也同样无法解锁它。

curl -X POST https://app.chaingateway.io/api/v2/tron/addresses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"password": "a-strong-password-per-wallet"}'

如果你的平台本来就自己生成密钥,第二个路由更合适:POST /api/v2/tron/addresses/import 会登记你在别处派生的地址,连同其私钥和加密密码,此后 API 就能为它签名。只想监控的地址则两个调用都不需要,因为 webhook 订阅是通过地址字符串来引用地址的。

同一组里还有两个管理路由。POST /api/v2/tron/addresses/{address} 修改已存私钥的加密密码。DELETE /api/v2/tron/addresses/{address} 把地址从你的账户中移除,参考文档说明这也会减少你已用的地址数量。如果你接近套餐上限,值得把它接入回收过期存款地址的任务里。

如何监控 TRC20 地址的 USDT 到账?

靠轮询 Tronscan 来检查存款,是最容易悄悄出问题的做法。POST /api/v2/tron/webhooks 才是可以扩展的做法。参考文档只把 url 标为必填;to 把订阅限定为转入你地址的存款,from 限定为从该地址转出的转账,contractaddress 限定为单一代币。type 选择资产类别,可取 TRX、TRC10、TRC20 或 TRC721。reference 最多可放 255 个字符的自定义文本,订单号或客户 ID 就该放在这里,这样通知到达时已经带着你的查询键。

curl -X POST https://app.chaingateway.io/api/v2/tron/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-backend.example/hooks/tron",
    "to": "TYourDepositAddress",
    "type": "TRC20",
    "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "reference": "customer-4711"
  }'

在账户中设置个人密钥后,每次送达都会带一个 X-Signature 头,它是对载荷中 txid 做 HMAC-SHA256 后再 base64 编码的值。解析其他内容之前先验证它。失败的送达不会自动重发:GET /api/v2/tron/webhooks/notifications/failed 列出没有送达的通知,POST /api/v2/tron/webhooks/notifications/{id}/retry 则会再发送一次。条目在重试开始时离开失败列表,只有这次重试也失败,才会再回来。重试会把同一事件再送达一次,所以请把每笔已入账存款的交易哈希存在唯一约束之下,让数据库拒绝重复。签名代码和载荷格式见 webhook 指南。

如何从该地址发送 USDT-TRC20?

POST /api/v2/tron/transactions/trc20 需要四个字段:from、to、contractaddress 和 amount。金额是以代币为单位的普通数字,所以 25 USDT 就是 25,而不是按合约的 6 位小数放大后的值。另外还要传 password(密钥由 API 加密保管时)或 privatekey(密钥由你自己保管时)二选一。

contractaddress 字段把钱包地址和代币合约地址的区别变成了具体的集成规则:合约地址标识的是哪一种代币在转移,它绝不是收款地址。USDT 的合约地址是 TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t,它应当填在 contractaddress 中,绝不能填在 to 里。发送到合约地址的代币在几乎所有情况下都无法找回。博客指南解释了两者为什么看起来一样:两者都是以 T 开头的字符串,字符串本身无法区分。

发送消耗 Energy 和 Bandwidth,接收则免费,所以存款系统是在归集时付费,而不是在存款时付费。TRON 手续费计算器可以估算某笔具体转账的费用,GET /api/v2/tron/chainparameters 返回实时的资源价格,这样你的代码不必写死一个会被治理投票改变的常量。

发送前如何校验 TRC20 地址?

用户一提交目标地址就检查,而不是等广播之后。TRC-20 地址有 34 个字符,以 T 开头,并带有 Base58Check 校验和,错一个字符就会破坏它,所以无需访问网络,就能区分格式正确的字符串和手误。想手动验证单个地址时,地址校验工具会在浏览器中对 TRC-20、ERC-20 和 BEP-20 做这项检查。

TRON 地址和 EVM 地址不会被误认,因为两者的格式差别明显:以 T 开头的字符串通不过 Ethereum 的校验,以 0x 开头的字符串通不过 TRON 的校验。TRON 的 TVM 能运行大部分为 EVM 编写的 Solidity 代码,但它是独立的运行时,有自己的资源计量方式(用 Energy 和 Bandwidth 代替 gas)和自己的地址编码。把「TRON EVM」当成字面意思,就是跨链地址错误的起点。

在搭建需要大量 TRC20 地址的收银台或交易所后端?创建免费账户,在测试网批量生成:7 天试用,无需信用卡,无需 KYC。

常见问题:TRC20 地址 API

POST /api/v2/tron/addresses 创建一个地址。请求体中传入 password,私钥就用它加密保存;不传 password,响应会返回私钥,由你自行保存。加上请求头 X-Network: testnet,可先在 TRON 测试网生成。

用 POST /api/v2/tron/webhooks 注册 webhook。把 url 设为你的端点,to 设为存款地址,type 设为 TRC20,contractaddress 设为代币合约。每次送达都带有 X-Signature 头,入账前先验证它。

不会。GET /api/v2/tron/webhooks/notifications/failed 列出没有送达的通知,POST /api/v2/tron/webhooks/notifications/{id}/retry 在你调用时重发一次。请自行规划恢复路径,并让入账逻辑具备幂等性,因为重试会把同一事件再送达一次。

不需要。webhook 订阅通过字符串引用地址。只有从地址发送时才需要私钥,可以用 POST /api/v2/tron/addresses/import 导入,也可以在转账调用中传入 privatekey。

填在 contractaddress 字段,绝不能填在 to 里。它标识的是哪一种 TRC-20 代币在转移;USDT 的合约地址是 TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t。发送到合约地址的代币在几乎所有情况下都无法找回。

GET /api/v2/tron/balances/{address}/trc20/{contract_address} 返回单个 TRC-20 代币的余额。GET /api/v2/tron/balances/{address} 返回 TRX 余额,地址发送时需要用它来支付 Energy 和 Bandwidth。

用户看到的 Base58Check 形式是以 T 开头的 34 个字符,同一个地址写成十六进制则以 41 开头。格式、校验和以及两种写法之间的转换,在指南《什么是 TRC20 地址?》中有说明。

准备好创建第一个 TRC20 地址了吗?

创建账户,今天就生成一个测试网 TRC20 地址:7 天试用,无需信用卡,无需 KYC。完整接口参考在 TRON API 页面,格式问题在什么是 TRC20 地址?中有解答,全部七条链则通过多链区块链 API使用同一套数据结构。

审核: Maurice Sobiera 我们如何撰写这些页面