简介这份资源面向需要接入波场链进行开发的Java工程师聚焦TRC20代币与TRX原生转账、地址生成等常见链上操作基于官方API文档整理出一套可直接参考的对接示例。压缩包共8个文件约2.78MB包含2个Java源码文件承载核心业务逻辑2个jar包提供依赖支持2个xml用于Maven构建与项目配置另有说明文档与忽略配置整体结构精简便于快速导入IDE运行调试。内容围绕TRX与USDT等TRC20资产的交易转账、账户地址生成等场景展开读者可据此理解官方接口的调用方式、参数组织与返回处理并在此基础上扩展余额查询、交易签名、广播上链等功能。目前已有75人学习下载适合具备一定Java基础、希望低成本跑通波场链对接流程的开发者作为起步模板与排错参考。1. 从一笔 TRX 转账说起Java 对接 TRC20 到底难在哪很多做 Java 后端的同学第一次接到「对接 TRC20 转账」的需求时第一反应是去找官方 API 文档然后发现文档里全是 HTTP 接口和签名规则没有一段能直接跑的 Java 代码。于是开始搜「TRC20 Java demo」搜出来的要么是几年前的 TronGrid 示例要么是别人封装好的 SDK 但版本对不上。真正卡住人的不是「怎么发请求」而是「签名怎么签、地址怎么生成、广播失败怎么排查」这三件事。这个标题要解决的核心问题很具体用 Java 通过官方 HTTP API 完成 TRX 和 TRC20 代币的转账同时能生成新地址。它适合有 Java 基础、需要在自己的服务里集成波场链上转账能力的后端开发不适合只想了解区块链概念的人。下面按「先跑通最小闭环再补签名和广播细节最后处理踩坑」的顺序展开每一步都给可复现的代码和参数说明。2. 环境准备与最小可运行工程把依赖和密钥先理清楚2.1 选 HTTP 直连还是 SDK为什么我倾向自己封装官方文档提供的是 REST 接口常见做法有两种一是引入 tron-java 这类第三方 SDK二是用 OkHttp 或 HttpClient 直接调接口。SDK 的好处是方法名直观坏处是版本更新慢、依赖冲突多尤其是项目里已经有 Jackson 或 BouncyCastle 的时候很容易出现NoSuchMethodError。我一般会选 HTTP 直连只引入两个依赖一个 HTTP 客户端一个做 secp256k1 签名的库。!-- pom.xml 片段 -- dependency groupIdcom.squareup.okhttp3/groupId artifactIdokhttp/artifactId version4.12.0/version /dependency dependency groupIdorg.bouncycastle/groupId artifactIdbcprov-jdk18on/artifactId version1.78.1/version /dependencyOkHttp 负责发请求BouncyCastle 负责椭圆曲线签名。版本号写在这里是为了让你直接复制能跑实际项目里如果已有这两个依赖保持原有版本即可只要 BouncyCastle 不低于 1.70。注意不要同时引入多个版本的 bcprov否则签名时会报Invalid signature这个坑后面还会细说。2.2 节点地址和 API Key主网和测试网别混用官方公开节点是https://api.trongrid.io测试网是https://api.shasta.trongrid.io。如果你只是本地跑 demo用测试网就够了测试网的 TRX 可以从水龙头领。主网请求如果频率高需要在请求头里带TRON-PRO-API-KEY这个 key 在 TronGrid 注册后拿到免费额度对普通转账场景够用。public class TronClient { // 测试网节点主网换成 https://api.trongrid.io private static final String BASE_URL https://api.shasta.trongrid.io; // 如果节点要求 API Key在这里填入测试网通常可以不填 private static final String API_KEY ; private final OkHttpClient client new OkHttpClient.Builder() .connectTimeout(10, TimeUnit.SECONDS) .readTimeout(30, TimeUnit.SECONDS) .build(); public String post(String path, String jsonBody) throws IOException { Request.Builder builder new Request.Builder() .url(BASE_URL path) .post(RequestBody.create(jsonBody, MediaType.parse(application/json))); if (!API_KEY.isEmpty()) { builder.addHeader(TRON-PRO-API-KEY, API_KEY); } try (Response resp client.newCall(builder.build()).execute()) { if (!resp.isSuccessful()) { throw new IOException(HTTP resp.code() : resp.body().string()); } return resp.body().string(); } } }这段代码把节点地址、API Key、超时都集中在一个类里。connectTimeout设 10 秒是因为链上节点偶尔会慢但超过 10 秒基本可以判定网络有问题没必要一直等。readTimeout给 30 秒是因为广播交易后节点返回可能稍慢。如果你在容器里跑注意 DNS 解析要正常否则会报UnknownHostException这个和代码无关是环境问题。2.3 生成地址从私钥到 Base58 地址的完整链路生成地址不需要调接口本地就能算。流程是随机生成 32 字节私钥用 secp256k1 算出公钥取公钥最后 64 字节做 Keccak-256 哈希取后 20 字节作为地址体前面加0x41再做 Base58Check 编码。很多人卡在「为什么我算出来的地址和钱包对不上」多半是漏了0x41前缀或者用了 SHA-256 而不是 Keccak-256。import org.bouncycastle.jce.provider.BouncyCastleProvider; import org.bouncycastle.crypto.digests.KeccakDigest; import org.bouncycastle.math.ec.ECPoint; import org.bouncycastle.math.ec.ECCurve; import java.math.BigInteger; import java.security.SecureRandom; public class AddressGenerator { // secp256k1 曲线参数 private static final BigInteger P new BigInteger( FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEFFFFFC2F, 16); private static final BigInteger N new BigInteger( FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141, 16); private static final ECCurve CURVE new ECCurve.Fp(P, BigInteger.valueOf(0), BigInteger.valueOf(7), N, BigInteger.ONE); public static String[] generate() { SecureRandom random new SecureRandom(); BigInteger privKey; do { privKey new BigInteger(256, random); } while (privKey.compareTo(N) 0 || privKey.signum() 0); ECPoint point CURVE.getG().multiply(privKey).normalize(); byte[] pubBytes point.getEncoded(false); // 65 字节首字节 0x04 // 取公钥后 64 字节做 Keccak-256 KeccakDigest digest new KeccakDigest(256); digest.update(pubBytes, 1, 64); byte[] hash new byte[32]; digest.doFinal(hash, 0); // 取后 20 字节前面加 0x41 byte[] addrBody new byte[21]; addrBody[0] 0x41; System.arraycopy(hash, 12, addrBody, 1, 20); String address Base58Check.encode(addrBody); String privateKeyHex String.format(%064x, privKey); return new String[]{address, privateKeyHex}; } }Base58Check需要自己实现或引入工具类核心是先对addrBody做两次 SHA-256取前 4 字节做校验码拼在末尾再 Base58 编码。私钥用 64 位十六进制字符串保存不要用BigInteger.toString()否则会丢前导零。生成出来的地址以T开头测试网和主网格式一样只是节点不同。私钥一旦丢失无法找回建议生成后立即加密存储不要打印到日志里。3. 构造与签名交易TRX 和 TRC20 的差别在哪3.1 TRX 转账从 createTransaction 到广播的完整调用TRX 转账分两步先调/wallet/createtransaction拿到未签名交易再本地签名后调/wallet/broadcasttransaction广播。未签名交易里包含txID、raw_data、raw_data_hex等字段签名是对txID做 secp256k1 签名然后把签名结果放进signature数组。public class TrxTransfer { public static String transfer(TronClient client, String from, String to, long amountSun, String privateKey) throws Exception { // 1. 构造请求体 String body String.format( {\owner_address\:\%s\,\to_address\:\%s\,\amount\:%d,\visible\:true}, from, to, amountSun); String resp client.post(/wallet/createtransaction, body); JSONObject tx new JSONObject(resp); String txID tx.getString(txID); // 2. 对 txID 签名 byte[] txIdBytes Hex.decode(txID); byte[] signature Secp256k1.sign(txIdBytes, privateKey); tx.put(signature, new JSONArray().put(Hex.toHexString(signature))); // 3. 广播 return client.post(/wallet/broadcasttransaction, tx.toString()); } }amount的单位是 SUN1 TRX 1,000,000 SUN。visible:true表示地址用 Base58 格式如果传false则要用 hex 地址。签名函数Secp256k1.sign内部用 BouncyCastle 的ECDSASigner注意签名结果要转成 65 字节的rsv格式v是恢复标识通常是 0 或 1。广播返回的 JSON 里result:true表示成功code字段会给出失败原因比如BANDWITH_ERROR或SIGERROR。3.2 TRC20 转账多了一步合约调用数据编码TRC20 转账不是直接转 TRX而是调用合约的transfer(address,uint256)方法。需要先构造这个方法调用的 data前 4 字节是方法选择器a9059cbb接着 32 字节是接收地址去掉0x41前缀左补零再 32 字节是转账数量。然后调/wallet/triggersmartcontract而不是createtransaction。public static String transferTrc20(TronClient client, String from, String contract, String to, BigInteger amount, String privateKey) throws Exception { // 1. 编码 data String methodId a9059cbb; String toParam String.format(%064x, new BigInteger(1, Base58Check.decode(to))); String amountParam String.format(%064x, amount); String data methodId toParam amountParam; // 2. 构造请求 String body String.format( {\owner_address\:\%s\,\contract_address\:\%s\, \function_selector\:\transfer(address,uint256)\, \parameter\:\%s\,\fee_limit\:100000000,\visible\:true}, from, contract, toParam amountParam); String resp client.post(/wallet/triggersmartcontract, body); JSONObject result new JSONObject(resp); JSONObject tx result.getJSONObject(transaction); // 3. 签名并广播 String txID tx.getString(txID); byte[] signature Secp256k1.sign(Hex.decode(txID), privateKey); tx.put(signature, new JSONArray().put(Hex.toHexString(signature))); return client.post(/wallet/broadcasttransaction, tx.toString()); }fee_limit是能量费上限单位 SUN这里设 1 TRX。TRC20 转账消耗的是能量而不是带宽如果账户没有足够能量会燃烧 TRX 抵扣所以fee_limit要留够。parameter字段是去掉方法选择器后的参数部分有些节点要求传完整 data有些要求分开传以官方文档当前版本为准。转账数量要按代币精度换算比如 USDT 是 6 位小数转 1 USDT 要传1000000。3.3 签名库的坑为什么你的签名总是无效签名无效是最高频的问题现象是广播返回SIGERROR或Transaction signature validation failed。原因通常有三个一是私钥格式不对有人把 Base58 私钥直接当 hex 用二是签名时对txID做了额外哈希实际上txID本身就是 SHA-256 结果直接签即可三是 BouncyCastle 版本冲突导致曲线参数不一致。public class Secp256k1 { public static byte[] sign(byte[] data, String privateKeyHex) { BigInteger privKey new BigInteger(privateKeyHex, 16); ECDSASigner signer new ECDSASigner(new HMacDSAKCalculator(new SHA256Digest())); signer.init(true, new ECPrivateKeyParameters(privKey, domainParams)); BigInteger[] rs signer.generateSignature(data); // 规范 s 值避免 malleability BigInteger s rs[1]; if (s.compareTo(N.divide(BigInteger.TWO)) 0) { s N.subtract(s); } byte[] sig new byte[65]; byte[] rBytes to32(rs[0]); byte[] sBytes to32(s); System.arraycopy(rBytes, 0, sig, 0, 32); System.arraycopy(sBytes, 0, sig, 32, 32); sig[64] (byte) recoverV(rs[0], s, data, privKey); return sig; } }to32保证 r 和 s 都是 32 字节不足补零。recoverV计算恢复标识通常是 0 或 1如果算错也会导致签名无效。这段代码依赖 BouncyCastle 的ECDSASigner如果你项目里用的是其他加密库要确认曲线参数是 secp256k1 而不是 secp256r1两者名字像但完全不同。4. 避坑与排查转账失败时先看这五个地方4.1 广播返回 BANDWITH_ERROR带宽不够还是参数写错现象是广播后返回{result:false,code:BANDWITH_ERROR,message:Account resource insufficient}。原因是账户带宽不足TRX 转账消耗约 270 带宽新账户或频繁转账的账户很容易不够。解决方式是先冻结 TRX 换带宽或者直接燃烧 TRX 抵扣后者需要在createtransaction时不设fee_limit之外的额外参数节点会自动扣。注意测试网水龙头领的 TRX 带宽有限连续转几笔就会遇到。4.2 地址校验失败Base58 解码后长度不对现象是构造交易时报Invalid address或广播后SIGERROR。原因是地址 Base58 解码后不是 21 字节或者首字节不是0x41。常见错误是把以太坊地址0x开头 20 字节直接拿来用或者自己拼地址时漏了校验码。解决方式是用Base58Check.decode后检查长度和首字节测试网地址同样以T开头不要和以太坊混淆。4.3 能量不足导致 TRC20 转账失败现象是 TRC20 转账广播成功但执行失败返回OUT_OF_ENERGY。原因是合约调用消耗的能量超过账户可用能量且fee_limit设得太低无法抵扣。解决方式是提高fee_limit或者先通过冻结 TRX 获取能量。USDT 转账大约消耗 30000 多能量具体数值随合约状态变化建议fee_limit至少设 10 TRX。如果只是测试可以用测试网的 USDT 合约能量消耗和主网一致。4.4 节点返回 401 或 403API Key 没带或带错现象是请求返回401 Unauthorized或403 Forbidden。原因是主网节点要求TRON-PRO-API-KEY请求头没带或 key 无效就会拒绝。解决方式是检查请求头名称是否拼写正确key 是否过期。测试网通常不需要 key但如果你用的是第三方节点以对方文档为准。注意不要把 key 硬编码在代码里提交到仓库用环境变量或配置中心。4.5 交易一直 pendingtxID 对但链上查不到现象是广播返回成功但链上浏览器查不到这笔交易。原因是节点广播后交易进入内存池如果手续费太低或网络拥堵可能长时间不打包甚至被丢弃。解决方式是先查txID在节点上的状态调/wallet/gettransactionbyid如果返回空说明节点没收到。可以换一个节点重新广播或者提高fee_limit。测试网偶尔会重置遇到这种情况等几分钟再试。5. 进阶技巧把转账封装成可重试的服务5.1 用状态机管理交易生命周期单次转账调用在生产环境不够用因为网络抖动、节点切换、广播失败都需要重试。我一般会把一笔转账拆成「构造 → 签名 → 广播 → 确认」四个状态每个状态落库失败后从当前状态继续而不是从头再来。确认状态通过轮询/wallet/gettransactioninfobyid实现查到blockNumber就认为上链查到receipt.result就判断执行结果。public enum TxState { CREATED, SIGNED, BROADCAST, CONFIRMED, FAILED } public void processWithRetry(String txId, int maxRetry) { for (int i 0; i maxRetry; i) { try { TxState state loadState(txId); switch (state) { case CREATED: signAndSave(txId); break; case SIGNED: broadcastAndSave(txId); break; case BROADCAST: if (confirm(txId)) return; break; default: return; } } catch (Exception e) { log.warn(retry {} for tx {}, i, txId, e); sleep(1000L i); // 指数退避 } } markFailed(txId); }maxRetry建议设 3 到 5 次退避时间用1s、2s、4s。每次重试前先查链上状态避免重复广播。如果交易已经上链但状态还是BROADCAST直接更新为CONFIRMED不要重复发。5.2 多节点切换与超时参数公开节点偶尔会超时生产环境建议配置两个以上节点请求失败后自动切换。OkHttp 的connectTimeout设 5 秒readTimeout设 15 秒超过就换节点。切换逻辑放在TronClient里维护一个节点列表和当前索引失败后index (index 1) % nodes.size()。注意不同节点的 API Key 可能不同切换时要一起换。参数建议值说明connectTimeout5s连接超时超过换节点readTimeout15s读超时广播接口可放宽到 30smaxRetry3单节点重试次数fee_limit10 TRXTRC20 转账能量费上限轮询间隔3s确认交易时的查询间隔5.3 私钥管理别把私钥写在代码里私钥泄露等于资产丢失我见过有人把私钥写在application.yml里提交到 Git结果被扫链机器人转走。正确做法是用 KMS 或硬件钱包签名至少也要用环境变量注入并且加密存储。如果只是本地 demo生成地址后把私钥单独保存不要和代码放一起。签名服务最好独立部署只暴露签名接口不暴露私钥。5.4 验证方法用测试网跑通再上主网测试网和主网接口完全一致只是节点地址不同。建议先在 Shasta 测试网生成地址、领测试 TRX、跑通 TRX 和 TRC20 转账确认签名和广播逻辑无误后再切主网。测试网的 USDT 合约地址和主网不同不要混用。验证时用区块浏览器查txID确认result和receipt.result都是SUCCESS。我自己的习惯是每接一个新链先用最小金额在主网跑一笔确认到账后再放大金额。这个习惯帮我避免过好几次因为参数精度问题导致的资产损失。希望帮到你。本文还有配套的精品资源点击获取