TRC20 Address API: generate addresses and watch them for deposits

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.

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.

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.

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.