TronTransfer API

Energy-sponsored USDT (TRC-20) transfers on TRON. You keep custody — you sign every transaction; we rent and delegate the TRON energy your transfer needs, so your wallet pays one small flat TRX fee instead of burning 6.5–13.1 TRX of its own. Wallet short of TRX? The zero-TRX endpoints let the sender pay the fee in USDT instead.

• Base URL https://trontransfer.com
• Network TRON mainnet
• Token USDT TRC-20
• Auth none for the on-chain flow · API key for prepaid accounts

How a sponsored send works

A sponsored transfer is two signed transactions you submit together:

1. Fee tx — a plain TRX transfer of the quoted fee to our collectAddress.
2. USDT tx — your normal transfer(to, amount) call on the USDT contract.

The relay then, in order: broadcasts the fee and confirms it on-chain (proves payment) → rents + delegates energy to your wallet → broadcasts your USDT tx, which burns the delegated energy (≈0 TRX beyond the fee).

Quickstart (TronWeb)

import TronWeb from "tronweb";
const BASE = "https://trontransfer.com";
const tw = new TronWeb({ fullHost: "https://api.trongrid.io" }); // + your signer

async function sendUsdt(from, to, amountUsdt) {
  // 1) config — where the fee goes + the USDT contract
  const cfg = await (await fetch(`${BASE}/config`)).json();

  // 2) the exact fee for THIS recipient (warm vs cold pricing)
  const rcpt  = await (await fetch(`${BASE}/recipient?addr=${to}`)).json();
  const price = rcpt.pricing || cfg.pricing;          // { feeSun, feeTrx, profitable, ... }
  if (!price.profitable) throw new Error("Discounted transfer unavailable right now");

  // 3) build BOTH txs
  const feeTx = await tw.transactionBuilder.sendTrx(cfg.collectAddress, price.feeSun, from);
  const units = Math.round(amountUsdt * 1e6);         // USDT = 6 decimals
  let usdtTx = (await tw.transactionBuilder.triggerSmartContract(
    cfg.usdtContract, "transfer(address,uint256)", { feeLimit: 100_000_000 },
    [{ type: "address", value: to }, { type: "uint256", value: units }], from
  )).transaction;

  // 4) extend expiration so the relay can rent energy before the tx expires
  const feeExt  = await tw.transactionBuilder.extendExpiration(feeTx, 300);
  const usdtExt = await tw.transactionBuilder.extendExpiration(usdtTx, 300);

  // 5) sign BOTH (TronWeb returns the fully-signed tx object)
  const feeSigned  = await tw.trx.sign(feeExt);
  const usdtSigned = await tw.trx.sign(usdtExt);

  // 6) submit
  const res = await fetch(`${BASE}/v1/transfers`, {
    method: "POST", headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ feeTx: feeSigned, usdtTx: usdtSigned }),
  });
  const out = await res.json();
  if (!out.ok || !out.usdtTxid) throw new Error(out.message || "send failed");
  return out; // { ok:true, usdtTxid, feeTxid, ... }
}

Server-side (Node.js)

Same flow — the only difference is the signer. Instead of a browser wallet, TronWeb holds a private key and signs silently. Ideal for payout backends, exchange withdrawals, remittance tooling and bots that custody their own keys.

// npm i tronweb    ·    Node 18+ (global fetch)
const { TronWeb } = require("tronweb");
const BASE = "https://trontransfer.com";

// Your key signs — no browser wallet. Keep it in env/KMS, never in code.
const tw = new TronWeb({
  fullHost: "https://api.trongrid.io",
  privateKey: process.env.TRON_PRIVATE_KEY,
});
const from = tw.defaultAddress.base58;                // the key's own address

async function sendUsdt(to, amountUsdt) {
  // 1) config + this recipient's exact fee (warm vs cold)
  const cfg   = await (await fetch(`${BASE}/config`)).json();
  const rcpt  = await (await fetch(`${BASE}/recipient?addr=${to}`)).json();
  const price = rcpt.pricing || cfg.pricing;
  if (!price.profitable) throw new Error("Discounted transfer unavailable right now");

  // 2) build BOTH txs: the TRX fee + the USDT transfer
  let feeTx   = await tw.transactionBuilder.sendTrx(cfg.collectAddress, price.feeSun, from);
  const units = Math.round(amountUsdt * 1e6);         // USDT = 6 decimals
  let usdtTx  = (await tw.transactionBuilder.triggerSmartContract(
    cfg.usdtContract, "transfer(address,uint256)", { feeLimit: 100_000_000 },
    [{ type: "address", value: to }, { type: "uint256", value: units }], from
  )).transaction;

  // 3) extend expiration so the relay can rent energy in time
  feeTx  = await tw.transactionBuilder.extendExpiration(feeTx, 300);
  usdtTx = await tw.transactionBuilder.extendExpiration(usdtTx, 300);

  // 4) sign BOTH with your private key (you never broadcast)
  const feeSigned  = await tw.trx.sign(feeTx);
  const usdtSigned = await tw.trx.sign(usdtTx);

  // 5) submit — the relay broadcasts
  const res = await fetch(`${BASE}/v1/transfers`, {
    method: "POST", headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ feeTx: feeSigned, usdtTx: usdtSigned }),
  });
  const out = await res.json();
  if (!out.ok || !out.usdtTxid) throw new Error(out.message || "send failed");
  return out; // { ok:true, usdtTxid, feeTxid, ... }
}

Endpoints

GET/config

Static config + default pricing. Call once and cache briefly.

{
  "collectAddress": "TWYPXnJmykjfdXdTwzQeDhYaoXTFQVw666",
  "usdtContract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "trxUsd": 0.3253,
  "defaultRegion": "sea",
  "regions": ["sea", "global"],
  "pricing": { "feeTrx": 5.476, "feeSun": 5476000, "feeUsd": 1.78,
               "networkUsd": 2.23, "energy": 65000, "cold": false,
               "profitable": true, "savePct": 20 }
}

GET/recipient?addr=<base58>[&from=<base58>]

Recipient-specific info and the exact fee for a transfer to addr. The fee depends on whether the recipient already holds USDT — "warm" (65k energy) vs "cold" (131k). Also returns safety signals.

Always build the fee tx for pricing.feeSun. Warm ≈ 5.48 TRX; cold ≈ 10.76 TRX.

POST/v1/transfers

The sponsored send. Body: the two fully-signed tx objects. (With a prepaid API key in Authorization: Bearer, send only usdtTx: the fee is charged from your balance.)

Request

{ "feeTx":  { …signed TRX transfer… },
  "usdtTx": { …signed USDT transfer()… },
  "region": "sea" }

Success — 200

{ "ok": true, "status": "completed",
  "usdtTxid": "…", "feeTxid": "…",
  "amountUsdt": 200, "feeTrx": 5.476, "energyFeeTrx": 0 }

Failure — 4xx (validation) or 200 { ok:false } (mid-flight)

{ "ok": false, "code": "FEE_TOO_LOW",
  "message": "Fee too low: paid 2.10 TRX, need at least 5.48 TRX for this transfer.",
  "detail": { "paidTrx": 2.1, "requiredTrx": 5.48 } }

POST /process is a legacy alias of /v1/transfers (same behavior).

GET/receipt?txid=<usdt_txid>

Solidified receipt — proves the energy was sponsored.

{ "result": "SUCCESS", "energyUsed": 64895, "energyFee": 0, "netFee": 0 }

energyFee: 0 confirms the transfer burned delegated (sponsored) energy, not the sender's TRX.

AML / address screening (optional, paid)

• GET/scan/quote?provider=bitok|elliptic — the price of one scan.
• POST/scan { address, provider, payTx } — a full AML / sanctions / mixer / darknet scan. payTx is a signed TRX fee tx to collectAddress. Returns a risk verdict, risk_score, is_sanctioned and detailed flags / exposure.
• POST/screen { recipient, amount } — a lightweight pre-send risk check.

bitok = local/SEA (cheaper); elliptic = worldwide (deeper). Recently-scanned addresses return cached at no extra cost.

Fee paid in USDT (zero-TRX)

For senders who hold USDT but little or no TRX. The wallet signs two ordinary USDT transfer() calls and sends them to us unbroadcast:

1. Fee tx (feeTx) — the quoted fee in USDT to feeAddress from the quote.
2. Payment (payTx) — the USDT you're sending, to the recipient.

We supply the energy and bandwidth for both, so the sender's TRX balance can be 0. In order: bandwidth for both + energy for the fee transfer → broadcast feeTx and wait until it's in a block → energy for the payment → broadcast payTx. Typically 15–45 s.

GET/zt/status[?sender=<base58>]

Whether the mode is available. Pass sender to ask for a specific wallet. Only offer the option when enabled is true.

{ "ok": true, "enabled": true, "paused": false, … }

GET/zt/quote?sender=<base58>&recipient=<base58>

{ "ok": true, "sender": "T…", "recipient": "T…",
  "feeAddress": "TAEHWm1AWH9ZisXg5HpJeJ8q7nbq8i4pXZ",
  "feeUsdt": <number>,          // the fee in USDT, for display
  "feeUnits": "<string>",       // the fee in USDT base units (6 decimals)
  "energy": <number>, "validS": 120 }

• Build the fee transfer for exactly feeUnits to feeAddress (always take both from the quote).
• validS: re-quote if more than ~2 minutes pass. /zt/process re-prices and accepts a fee from 95 % to 300 % of a fresh quote (FEE_TOO_LOW / FEE_TOO_HIGH otherwise, with requiredUsdt).

POST/zt/process

Request — two signed, unbroadcast USDT transfer() transactions from the same sender

{ "feeTx": { …signed transfer(feeAddress, feeUnits)… },
  "payTx": { …signed transfer(recipient, amount)… } }

Answer — when both transfers are in a block

{ "ok": true, "status": "completed", "sender": "T…", "recipient": "T…",
  "amount": "10000000", "feeUnits": "…", "feeTxid": "…", "payTxid": "…" }

If that takes longer than 40 s you get { "ok": false, "status": "processing", "code": "PROCESSING", "feeTxid": "…", … }: the job keeps running on the server — poll /zt/job. Never broadcast the two transactions yourself, and never sign a new pair while one is processing. Sending the same pair again (a retry, a double click) is safe: it never spends twice, it returns or resumes the same job.

const BASE = "https://trontransfer.com", USDT = "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t";
// sender = the connected address; amountUnits = USDT × 1e6
const q = await (await fetch(`${BASE}/zt/quote?sender=${sender}&recipient=${to}`)).json();
if (!q.ok) throw new Error(`${q.code}: ${q.message}`);
const build = async (dest, units) => {
  let { transaction: tx } = await tronWeb.transactionBuilder.triggerSmartContract(USDT, "transfer(address,uint256)",
    { feeLimit: 30e6, callValue: 0 }, [{ type: "address", value: dest }, { type: "uint256", value: units }], sender);
  // expiry ~8 min after the node built it, whatever the node's default is
  const ext = Math.round((tx.raw_data.timestamp + 480000 - tx.raw_data.expiration) / 1000);
  if (ext) tx = await tronWeb.transactionBuilder.extendExpiration(tx, ext);
  return tronWeb.trx.sign(tx);                        // sign only; never broadcast
};
const feeTx = await build(q.feeAddress, q.feeUnits), payTx = await build(to, amountUnits);
let out = await (await fetch(`${BASE}/zt/process`, { method: "POST", headers: { "content-type": "application/json" },
  body: JSON.stringify({ feeTx, payTx }) })).json();
while (out.status === "processing") {
  await new Promise((r) => setTimeout(r, 4000));
  out = await (await fetch(`${BASE}/zt/job?fee=${feeTx.txID}`)).json();
}

GET/zt/job?fee=<fee txid>

The current answer for that send, in the same shape as /zt/process: completed, pay_failed, processing, or failed with a code. { "ok": false, "code": "NOT_FOUND" } if the relay never accepted that pair. Poll every 3–5 s; most jobs end in under a minute, and every job ends within ~25 minutes of its transactions being signed.

Reading an answer

All responses are HTTP 200 JSON — check ok and status, never the HTTP status.

• status: "completed" → sent.
• status: "pay_failed" → the fee was charged and the payment was not sent (certain). Show both txids and contact support.
• status: "processing" → keep polling /zt/job. Don't say anything about money yet.
• A code in the nothing-charged list below → nothing was broadcast; you may say so.
• Any other code (including UNCONFIRMED, INTERNAL_ERROR, DUPLICATE, or a code added later) → uncertain: don't send again yet; check both transfers on Tronscan. Never report "nothing charged" or "not sent" for these.

Nothing-charged list (mirror it exactly):

DISABLED MISCONFIGURED PAUSED RATE_LIMITED BUSY REFUSED BAD_ADDRESS PRICE_UNAVAILABLE
INVALID_JSON TX_MISSING TX_TAMPERED NOT_A_TRANSFER WRONG_TOKEN VALUE_ATTACHED MEMO_NOT_ALLOWED
FEE_LIMIT_TOO_LOW ZERO_AMOUNT BAD_SIGNATURE PERMISSION TX_EXPIRING SENDER_MISMATCH
FEE_WRONG_DESTINATION PAY_TO_FEE_ADDRESS SAME_TX FEE_TOO_LOW FEE_TOO_HIGH ACCOUNT_INACTIVE
INSUFFICIENT_USDT WOULD_FAIL BANDWIDTH_SHORT ENERGY_UNAVAILABLE ENERGY_TIMEOUT FEE_NOT_PAID

Prepaid API accounts

For developers and agents that send often. Instead of signing a TRX fee transaction for every transfer, you hold a TRX balance with us and send each transfer with an API key: the relay charges the fee from the balance, rents the energy and broadcasts your signed USDT transfer. The on-chain flow above keeps working exactly as before without a key.

When it fits

• Payout backends, bots and agents that send many transfers: one balance to top up, one signature per send, no per-transfer fee confirmation (typically 3–6 s saved).
• Several sending wallets behind one account: any wallet can sign the USDT transfer; the fee always comes off the account balance, not the signing wallet.
• Wallets that hold USDT but little TRX: the signing wallet does not pay the fee itself. Keep a little TRX in it anyway — bandwidth sponsorship is best-effort, and a wallet with no bandwidth left burns ~0.3 TRX for the transfer.

For a single occasional send, the on-chain flow (no account) is simpler. Dashboard for humans: trontransfer.com/account.

1. Get a key

curl -X POST https://trontransfer.com/account/keys \
  -H "Content-Type: application/json" -d '{ "label": "payout bot" }'

HTTP 201
{ "ok": true,
  "key": "tt_live_…",                       // shown ONCE — store it server-side
  "account": { "id": 42, "keyPrefix": "tt_live_a1b2", "label": "payout bot",
               "depositCode": "TT-7K4MQ2", "balanceSun": 0, "balanceTrx": 0,
               "status": "active", "createdAt": "…", "lastUsedAt": null },
  "depositAddress": "TWYPXnJmykjfdXdTwzQeDhYaoXTFQVw666" }

• The key is shown once and stored hashed; we cannot show it again. Lost it? POST /account/rotate needs the old key, so contact support.
• Up to 5 new keys per hour per IP. Keys are tt_live_ + 32 characters; send them only in the Authorization header, never in a URL or a browser page.
• POST /account/rotate (Bearer) returns a new key; the old one stops working at once.

2. Deposit TRX

Deposits are plain TRX transfers to depositAddress (the same address as collectAddress in /config; also in GET /account/pricing). We credit a deposit once its transaction is confirmed — the watcher checks about every minute, and POST /account/check-deposits looks right now. Two ways to tell us whose deposit it is:

// TronWeb: a 100 TRX deposit with the memo code
let tx = await tw.transactionBuilder.sendTrx(depositAddress, 100_000_000, from);
tx = await tw.transactionBuilder.addUpdateData(tx, "TT-7K4MQ2", "utf8");   // the memo
await tw.trx.sendRawTransaction(await tw.trx.sign(tx));   // a deposit IS broadcast by you (unlike a transfer)

3. Send with a key

Same as POST /v1/transfers, with Authorization: Bearer <key> and only usdtTx in the body: your signed, unbroadcast USDT transfer() with the expiration extended to ~5 minutes (the relay rents energy before it broadcasts; at most 15 minutes, else 400 TX_EXPIRATION_TOO_LONG). No feeTx — a fee transaction sent with a key is ignored.

curl -X POST https://trontransfer.com/v1/transfers \
  -H "Authorization: Bearer tt_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "usdtTx": { "txID": "…", "raw_data": { … }, "raw_data_hex": "…", "signature": ["…"] } }'

Node.js (TronWeb) — build, sign, submit

// npm i tronweb    ·    Node 18+ (global fetch)
const { TronWeb } = require("tronweb");
const BASE = "https://trontransfer.com";
const tw = new TronWeb({ fullHost: "https://api.trongrid.io", privateKey: process.env.TRON_PRIVATE_KEY });
const from = tw.defaultAddress.base58;
const headers = { "Content-Type": "application/json", "Authorization": `Bearer ${process.env.TT_API_KEY}` };

async function sendUsdt(to, amountUsdt) {
  // 1) the USDT contract + this recipient's fee (what will be charged) and safety signals
  const cfg  = await (await fetch(`${BASE}/config`)).json();
  const rcpt = await (await fetch(`${BASE}/recipient?addr=${to}`)).json();
  if (rcpt.blacklisted) throw new Error("recipient is blacklisted; do not send");
  if (!(rcpt.pricing || cfg.pricing).profitable) throw new Error("sponsorship paused right now; retry later");

  // 2) build + sign ONLY the USDT transfer — no fee tx, the fee comes off your balance
  let usdtTx = (await tw.transactionBuilder.triggerSmartContract(
    cfg.usdtContract, "transfer(address,uint256)", { feeLimit: 100_000_000 },
    [{ type: "address", value: to }, { type: "uint256", value: Math.round(amountUsdt * 1e6) }], from
  )).transaction;
  usdtTx = await tw.transactionBuilder.extendExpiration(usdtTx, 300);   // ~5 min: energy is rented first
  const usdtSigned = await tw.trx.sign(usdtTx);                          // sign only — never broadcast

  // 3) submit with your key
  const res  = await fetch(`${BASE}/v1/transfers`, { method: "POST", headers, body: JSON.stringify({ usdtTx: usdtSigned }) });
  const text = await res.text();
  let out; try { out = JSON.parse(text); } catch { out = null; }
  if (!out) return { ok: null, status: "unknown", checkTxid: usdtSigned.txID }; // gateway timeout: check /receipt, never resend blindly
  if (res.status === 402) throw new Error(`top up: balance ${out.detail.balanceTrx} TRX, need ${out.detail.requiredTrx} TRX (memo ${out.depositCode} to ${out.depositAddress})`);
  if (!out.ok) throw new Error(`${out.code}: ${out.message}`);
  return out; // { ok:true, status:"completed", usdtTxid, prepaid:{ chargedTrx, balanceTrx, tier } }
}

Success — 200

{ "ok": true, "status": "completed",
  "usdtTxid": "…", "feeTxid": "prepaid:<usdtTx.txID>",      // the ledger reference, not a chain tx
  "amountUsdt": 200, "feeTrx": 5.48, "energyFeeTrx": 0,
  "prepaid": { "chargedTrx": 5.48, "balanceTrx": 494.52,
               "tier": { "count": 12, "windowDays": 30, "minCount": 0, "mult": 1, "discountPct": 0 } } }

Balance too low — 402 (nothing charged)

{ "ok": false, "code": "INSUFFICIENT_BALANCE",
  "message": "Your balance must cover the current cold-recipient fee (10.76 TRX) to send.",
  "detail": { "balanceTrx": 3.2, "requiredTrx": 10.76, "chargeTrx": 5.48 },
  "depositAddress": "TWYPXnJmykjfdXdTwzQeDhYaoXTFQVw666", "depositCode": "TT-7K4MQ2" }

Reading the answer

Judge by ok and code, as for every /v1/transfers call. What happened to the charge:

• Not JSON (gateway timeout): the transfer may still be running. Check /receipt?txid=<usdtTx.txID> first; GET /account/me shows the charge or refund.
• Resending the same signed usdtTx never pays twice: it is answered with DUPLICATE and nothing is charged again.
• Every movement is a ledger row (deposit, charge, refund, adjust) in GET /account/me; a charge or refund's ref is prepaid:<usdt txID>.

How a charge is settled

• Open charges are settled from the chain by a reconciler that runs at start-up and every 5 minutes. It never refunds on a throttled or lagging node's say-so: "not on the chain" is believed only from a node that is up to date, so a decision may wait for a later run.
• Every refund happens at most once per transfer and shows as a refund row in the ledger.

Account endpoints

All JSON; { ok:false, code, message } on failure. Bearer = Authorization: Bearer tt_live_….

Every endpoint answers 503 PREPAID_UNAVAILABLE while prepaid accounts are switched off; 429 RATE_LIMITED when a limit above is hit.

Pricing

• Per transfer: the live on-chain fee for that recipient — pricing.feeSun from /recipient (warm ≈ 5.48 TRX, cold ≈ 10.76 TRX right now) — times your tier multiplier. It is never below our own network cost; a charge floored there is rounded up to the next 0.1 TRX.
• Volume tiers (trailing 30 days, counted per account): 100+ transfers → ×0.85 (15% less); 500+ → ×0.70 (30% less). Your current tier and count are in prepaid.tier on every answer and in GET /account/me.
• Entry bar: a transfer is accepted only when the balance is at least the current cold fee (prices.charge.minBalanceTrx), even when the recipient is warm — otherwise 402 INSUFFICIENT_BALANCE and nothing is charged.
• Refunds: automatic and in full when nothing was bought for the transfer and it never went out; once energy or bandwidth was bought, or it was broadcast and failed on-chain, only the network cost we paid is kept (rules.failedOnchain: "cost") — see how a charge is settled.
• Balances never expire. Withdrawals on request: email [email protected] from the account's label or with its deposit code.

Error codes (/v1/transfers)

Notes & gotchas

• Mainnet only. No testnet.
• 6 decimals. USDT amount units = usdt × 1_000_000.
• Flat fee per transfer, independent of the USDT amount — driven by energy (warm 65k / cold 131k), not size.
• Extend expiration to ~300s on both txs; the relay withholds the USDT broadcast until energy is delegated (~15–45s).
• The fee is real and paid up-front to collectAddress. If a transfer fails after the fee confirms (ENERGY_UNAVAILABLE), the USDT is not sent and the fee is not auto-refunded — retry to reuse it, or reconcile. (A prepaid charge, by contrast, is returned to the balance automatically when nothing was bought for the transfer; otherwise it is settled from the chain.)
• Idempotent: a signed tx has a fixed txID; re-submitting the same pair is safe (the network rejects a duplicate broadcast; with a key the answer is DUPLICATE and nothing is charged again).