TRC20 Address API: generate addresses and watch them for deposits
A TRC20 address is a standard TRON account address: 34 characters in Base58Check form, starting with T. It holds TRX and every TRC-20 token such as USDT. The same address has a 42-character hex spelling that begins with 41. Sending from it costs Energy and Bandwidth, while receiving is free.
To generate a TRC20 address over an API, call POST /api/v2/tron/addresses. The response is a T-prefixed Base58Check address. A webhook registered with POST /api/v2/tron/webhooks then reports every USDT-TRC20 deposit to it. This page explains the format first, then creation, monitoring and sending, with endpoints and request bodies.
Everything below runs against https://app.chaingateway.io with a Bearer token in the Authorization header. Adding X-Network: testnet to any call moves it to the TRON testnet, so the whole flow can be rehearsed with free test TRX. For a longer explainer on the format, see What is a TRC20 address? on the blog.
What does a TRC20 address look like?
A TRC20 address is a TRON account address in its Base58Check form, for example TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL. It has 34 characters and starts with T. TRON's account documentation defines the underlying value as 21 bytes: a leading 0x41 prefix byte, then 20 bytes that match the Ethereum address derived from the same public key.
The same address therefore has a hex spelling of 42 characters that begins with 41. Node APIs often return that form, while wallets and explorers show the Base58Check one. TronWeb converts between them with tronWeb.address.toHex() and fromHex().
"TRC20" names the token standard, not the address. TRC-20 is TRON's fungible-token standard and is compatible with Ethereum's ERC-20 at the interface level. One TRON address holds TRX and every TRC-20 token.
- The Base58Check form shown in wallets and explorers: 34 characters, starting with T.
- The 41 prefix byte marks the value as a TRON address.
- The remaining 20 bytes are identical to the Ethereum address derived from the same public key.
- The hex form: 42 characters in total, as returned by many node APIs.
Is a TRC20 address the same as a TRC20 contract address?
No. A wallet address is an account controlled by a private key. A contract address belongs to deployed code, and nobody holds a key for it. TRON's documentation lists both as account types, and both are written as T strings, so nothing in the string tells them apart.
The contract address identifies which token moves. It is never the destination of a transfer. USDT's TRC-20 contract is TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t, and tokens sent to a contract address are, in almost every case, unrecoverable. The blog guide explains the difference in more detail.
Why does a new TRC20 address not show up on Tronscan?
Because TRON only recognizes an account after activation. Per TRON's account documentation, a freshly generated key pair exists locally, but the address cannot be looked up through the API or a block explorer until it is activated.
Activation happens when an existing account sends the new address any amount of TRX or a TRC-10 token, and the sender pays an account creation fee. The documentation gives that fee as 1 TRX on mainnet at the time of writing, so check the current value before you plan a payout flow around it. A generated address is fine for deposits and webhooks, but do not expect an explorer to display it before its first activation.
TRC20 address endpoints: create, read, watch, send
Four jobs, and the routes that do them. Address creation and webhook registration need no private key at all; only sending does.
| Endpoint | What it does |
|---|---|
POST /api/v2/tron/addresses | Generate a new TRON address |
POST /api/v2/tron/addresses/import | Import an existing private key so the API can sign for that address |
POST /api/v2/tron/addresses/{address} | Change the password that encrypts a stored key |
DELETE /api/v2/tron/addresses/{address} | Remove an address from your account |
GET /api/v2/tron/balances/{address} | TRX balance of the address |
GET /api/v2/tron/balances/{address}/trc20/{contract_address} | Balance of one TRC-20 token, USDT included |
GET /api/v2/tron/balances/{address}/trc10/{token_id} | Balance of a TRC-10 token |
POST /api/v2/tron/webhooks | Subscribe to TRX, TRC-10, TRC-20 or TRC-721 transfers for the address |
GET /api/v2/tron/webhooks/notifications | List the notifications already delivered, for reconciliation |
POST /api/v2/tron/transactions/trc20 | Send a TRC-20 token such as USDT from the address |
That is the whole surface a deposit system touches. The complete TRON reference, all 40 operations including staking and self-signing, is on the TRON API page. The type field on a webhook and the separate /transactions/trc10 route exist because TRON carries two token standards. The TRC10 vs TRC20 comparison covers which one to issue on if you are launching a token rather than accepting an existing one.
How do I generate a TRC20 address over REST?
POST /api/v2/tron/addresses creates one. The body takes a single optional field, password, and that field decides the custody model. Send a password and the private key is stored encrypted behind it, so later transfers authenticate with the password instead of the key. Leave it out and the response hands you the private key directly, for storage in your own vault. The reference is explicit that passwords are not stored: lose it and the wallet cannot be restored, which is the same sentence read from the other side — nobody else can unlock it either.
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"}'
If your platform already generates keys itself, the second route fits better: POST /api/v2/tron/addresses/import registers an address you derived elsewhere, together with its private key and an encryption password, and the API can sign for it from then on. Addresses you only want to watch need neither call, because a webhook subscription references an address by string.
Two housekeeping routes belong to the same set. POST /api/v2/tron/addresses/{address} changes the encryption password on a stored key. DELETE /api/v2/tron/addresses/{address} removes the address from your account, which the reference notes also lowers your used-address count — worth wiring into the job that retires expired deposit addresses if you run close to a plan limit.
How do I watch a TRC20 address for incoming USDT?
Polling Tronscan for deposits is the version of this that breaks quietly. POST /api/v2/tron/webhooks is the version that scales. url is the only field the reference marks as required; to narrows the subscription to deposits at your address, from to transfers leaving it, and contractaddress to a single token. type selects the asset class and accepts TRX, TRC10, TRC20 or TRC721. reference holds up to 255 characters of your own text, which is where the order or customer ID belongs so the notification arrives with your lookup key already attached.
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"
}'
Set a personal secret in your account and every delivery carries an X-Signature header, a base64-encoded HMAC-SHA256 over the payload's txid. Verify it before you parse anything else. Nothing re-sends a failed delivery on its own: GET /api/v2/tron/webhooks/notifications/failed lists what never got through, and POST /api/v2/tron/webhooks/notifications/{id}/retry is the call that sends one again. An entry leaves the failed list when its retry starts and comes back only if that retry fails too. Because a retry delivers the same event a second time, store the transaction hash of every credited deposit under a unique constraint and let the database reject the duplicate. Signature code and payload shapes are in the webhook guide.
How do I send USDT-TRC20 out of the address?
POST /api/v2/tron/transactions/trc20 requires four fields: from, to, contractaddress and amount. The amount is a plain number in token units, so 25 USDT is 25, not a value scaled by the contract's six decimals. Alongside them you send either password, for a key the API holds encrypted, or privatekey, if you kept the key yourself.
The contractaddress field is where the distinction between a wallet address and a token contract address turns into a concrete integration rule: the contract address identifies which token moves, it is never the destination. USDT's is TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t, and it belongs in contractaddress, never in to. Tokens sent to a contract address are, in almost every case, unrecoverable. The blog guide explains why the two look identical — both are T strings, and nothing in the string tells them apart.
Sending costs Energy and Bandwidth while receiving is free, so a deposit system pays on the sweep rather than on the deposit. The TRON fee calculator prices a specific transfer, and GET /api/v2/tron/chainparameters returns the live resource prices so your code never hard-codes a constant that a governance vote invalidates.
How do I validate a TRC20 address before sending?
Check the destination the moment a user submits it, not after the broadcast. A TRC-20 address is 34 characters, starts with T and carries a Base58Check checksum that a single mistyped character breaks, so a well-formed string can be told from a typo without touching the network. The address validator runs that check for TRC-20, ERC-20 and BEP-20 in the browser when you want to verify one address by hand.
One thing the check cannot do is tell a TRON address from an EVM one by accident, because the formats differ visibly: a T string fails Ethereum's validation and a 0x string fails TRON's. TRON's TVM runs much of the Solidity written for the EVM, but it is a separate runtime with its own resource metering, Energy and Bandwidth instead of gas, and its own address encoding. Treating "TRON EVM" as literally true is where cross-chain address bugs start.
Sources
Building a checkout or exchange backend that needs TRC20 addresses at scale? Create a free account and generate a batch on testnet — 7-day trial, no card, no KYC.
FAQ: the TRC20 address API
Ready to create your first TRC20 address?
Create an account and generate a testnet TRC20 address today — 7-day trial, no card, no KYC. The full endpoint reference sits on the TRON API page, the format question is answered in What is a TRC20 address?, and all seven chains run through the same schema in the multi-chain blockchain API.
Reviewed by Maurice Sobiera How we write these pages