Getting started
Sign in to your personal account and open the API tab to obtain your Base URL and API key.
Open accountSet these variables in your terminal. Copy the Base URL from your account without a trailing slash.
export BASE_URL="https://YOUR_API_BASE_URL"
export API_KEY="YOUR_API_KEY"Send X-API-Key for balance, tariffs and orders. The fee estimate endpoint is public and needs no API key. Keep your key on your backend, not in browser code.
Check balance → estimate Energy → fetch tariffs → place an order
Energy is delegated to the wallet sending USDT. recipient_wallet in the estimator is the destination of the USDT transfer.
New: prepare a USDT transfer in one call — we check the addresses, order Energy and Bandwidth for the sender and tell you when to send.
/v1/transfers/prepareNEWPrepare a USDT transfer
X-API-Key requiredChecks the sender (and, on request, the recipient), orders Energy and Bandwidth for the sender if needed, and tells you when the transfer can be sent.
Create a preparation → poll its status → send USDT when status = ready
Authorization: the X-API-Key header on every request.
Headers
X-API-KeyRequired- Your API key.
Idempotency-KeyRequired- A unique string, 1–128 characters. Use the same key when retrying the same request.
Content-Typeapplication/json
Request body
{
"sender": "TFCyGqE4QtizzWP******Sq28dVjQtDqk8od",
"recipient": "TCV4qdpTxoMyq******XmhH5JFxMvmT",
"check_recipient": true
}senderstring- USDT sender address; receives Energy and Bandwidth.
recipientstring- USDT recipient address.
check_recipientbool · default false- Screen the recipient for sanctions and other stop factors.
Request
curl -s -X POST "$BASE_URL/v1/transfers/prepare" \
-H "X-API-Key: $API_KEY" \
-H "Idempotency-Key: 94d00c23-d08e-4fc9-95e5-f23d86f46261" \
-H "Content-Type: application/json" \
-d '{"sender":"TFCyGqE4Qti******Sq28dVjQtDqk8od","recipient":"TCV4qdpTxo******hH5JFxMvmT","check_recipient":true}'Response 200 — a preparation object (see below) with status = processing, or ready right away.
/v1/transfers/prepare/{prepare_id}Get preparation status
X-API-Key requiredPoll every 2–3 seconds while status = processing. Returns the same preparation object.
Request
curl -s "$BASE_URL/v1/transfers/prepare/6" \
-H "X-API-Key: $API_KEY"Example: preparation is ready
{
"prepare_id": 6,
"status": "ready",
"can_transfer": true,
"required_energy": 131000,
"energy_package": 131000,
"bandwidth_required": false,
"sender_activated": true,
"estimated_cost_trx": "5.4",
"charged": {"total_trx": "5.4", "energy_trx": "5.4", "bandwidth_trx": "0", "activation_trx": "0"},
"sender_energy_available": 130999,
"sender_bandwidth_available": 600,
"energy_tx_id": null,
"topup_tx_id": null,
"error_code": null,
"message": null,
"created_at": "2026-11-12T21:04:50.070890",
"completed_at": "2026-11-12T21:04:50.070890"
}Preparation object
| Field | Description |
|---|---|
prepare_id | Preparation ID. |
status | processing / ready / failed / unknown. |
can_transfer | true — the transfer can be sent. |
required_energy | Energy needed: 65000 (recipient holds USDT) or 131000. |
energy_package | Ordered package; null if the sender already had enough Energy. |
bandwidth_required | Whether Bandwidth had to be bought. |
sender_activated | Whether the sender address was activated before the order. |
estimated_cost_trx | Estimated cost at creation time. |
charged | Actual charge; null while processing. |
sender_energy_available, sender_bandwidth_available | Latest data from the network. |
error_code, message | Reason when status is failed or unknown. |
charged · charged after completion
{"total_trx": "5.4", "energy_trx": "5.4", "bandwidth_trx": "0", "activation_trx": "0"}Statuses
| status | What to do |
|---|---|
processing | Keep polling. |
ready | Resources are confirmed on-chain — send the transfer. |
failed | The order was not fulfilled; you can create a new preparation with a new key. |
unknown | The result is not confirmed — do not create a new order, contact support. |
Errors on creation
Returned immediately, with no charge. Error body: {"detail": {"error": "<code>", "message": "<text>", ...}}
| HTTP | error | Reason |
|---|---|---|
400 | INVALID_TRON_ADDRESS | Invalid address. |
400 | SAME_ADDRESS | Sender is the same as the recipient. |
402 | INSUFFICIENT_BALANCE | Less than 2 TRX available, or not enough for the full cost (required_sun, available_sun). |
404 | TARIFF_NOT_FOUND | No tariff for the required package. |
409 | IDEMPOTENCY_KEY_REUSED | The key was already used with different parameters. |
451 | SENDER_SANCTIONEDRECIPIENT_SANCTIONED | Stop factor; the reason is in message, details in matches. |
503 | SANCTIONS_DATA_NOT_READYADDRESS_ACTIVATION_CHECK_UNAVAILABLETRON_DATA_UNAVAILABLE | Temporarily unavailable — retry later with the same key. |
422 | — | Missing Idempotency-Key or invalid body. |
Example: recipient on a sanctions list
{
"detail": {
"error": "RECIPIENT_SANCTIONED",
"message": "Address is present in sanctions lists.",
"party": "recipient",
"reason": "sanctions_hit",
"matches": [
{
"source": "ofac_sdn",
"asset": "TRX",
"list_version": "11/09/2026"
}
]
}
}Example: another stop factor — mass-spam sender
{
"detail": {
"error": "RECIPIENT_SANCTIONED",
"message": "Address is identified as a mass-spam sender.",
"party": "recipient",
"reason": "sanctions_hit",
"matches": [
{
"source": "blockchain_data",
"asset": "TRX",
"list_version": null,
"category": "spam_sender",
"reason_code": "SPAM_SENDER",
"reason": "Address is identified as a mass-spam sender.",
"label": null
}
]
}
}Retries
- Repeating a POST with the same Idempotency-Key and the same fields returns the same preparation — no new order and no new charge.
- On a timeout or a dropped connection, retry with the same key. A new key means a new paid order.
Full example
curl -s -X POST "$BASE_URL/v1/transfers/prepare" \
-H "X-API-Key: $API_KEY" \
-H "Idempotency-Key: 94d00c23-d08e-4fc9-95e5-f23d86f46261" \
-H "Content-Type: application/json" \
-d '{"sender":"TFCyGqE4Qti******Sq28dVjQtDqk8od","recipient":"TCV4qdpTxo******hH5JFxMvmT","check_recipient":true}'
curl -s "$BASE_URL/v1/transfers/prepare/6" \
-H "X-API-Key: $API_KEY"Examples are illustrative; tariff and order prices may differ.
/v1/me/balanceGet balance
X-API-Key requiredReturns the available service balance in TRX, with its SUN equivalent.
Request
curl "$BASE_URL/v1/me/balance" \
-H "X-API-Key: $API_KEY"Example response
{
"balance_sun": 19795000,
"balance_trx": 19.795
}/v1/public/fee-estimateEstimate required Energy
Public · no API keyDetermines the required Energy package. With a sender address, it also checks the resources available in that wallet.
Parameters
recipient_walletRequired- Recipient TRON address. Used to determine whether 65,000 or 130,000 Energy is required.
sender_walletOptional- Optional sender TRON address. Adds its Energy, Bandwidth and TRX balance to the estimate.
Recipient and sender
Request
curl "$BASE_URL/v1/public/fee-estimate?recipient_wallet=TTAFuzcJZyJidjNvbi9S9UviPaietqZ9if&sender_wallet=TTAFuzcJZyJidjNvbi9S9UviPaietqZ9if"Example response
{
"bandwidth_deficit": 0,
"code": "SENDER_LACKS_ENERGY",
"energy_deficit": 64991,
"has_enough_bandwidth": true,
"has_enough_energy": false,
"has_enough_trx_for_bandwidth": true,
"recipient_has_usdt": true,
"recommended_trx_topup": "0",
"required_energy": 65000,
"sender_bandwidth_available": 515,
"sender_energy_available": 9,
"sender_trx_balance": "36.279462"
}Recipient only
Request
curl "$BASE_URL/v1/public/fee-estimate?recipient_wallet=TTAFuzcJZyJidjNvbi9S9UviPaietqZ9if"Example response
{
"bandwidth_deficit": null,
"code": "RECIPIENT_USDT_65000",
"energy_deficit": null,
"has_enough_bandwidth": null,
"has_enough_energy": null,
"has_enough_trx_for_bandwidth": null,
"recipient_has_usdt": true,
"recommended_trx_topup": null,
"required_energy": 65000,
"sender_bandwidth_available": null,
"sender_energy_available": null,
"sender_trx_balance": null
}Without sender_wallet, sender resource fields are null: they have not been checked.
/v1/me/tariffsCurrent tariffs
X-API-Key requiredReturns the Energy packages available to your account. Prices below are examples; use this endpoint for your current price.
Request
curl "$BASE_URL/v1/me/tariffs" \
-H "X-API-Key: $API_KEY"Example response
[
{
"energy": 65000,
"price_trx": 2.7,
"currency": "TRX",
"_src": "public",
"discount_percent": null,
"discount_starts_at": null,
"discount_ends_at": null
},
{
"energy": 130000,
"price_trx": 4.5,
"currency": "TRX",
"_src": "personal",
"discount_percent": null,
"discount_starts_at": null,
"discount_ends_at": null
}
]/v1/orderOrder Energy
X-API-Key requiredDelegates the selected Energy package to a TRON wallet and deducts its cost from your service balance.
Energy is valid for 1 hour after delegation or until the first transfer, whichever comes first.
If the wallet is not activated, we activate it before delegating Energy. Activation costs an additional 1.2 TRX.
Calculate the required Energy before ordering →Request
curl -X POST "$BASE_URL/v1/order" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"wallet": "TYourTronWalletAddress",
"energy": 65000,
"trx_topup": false,
"trx_topup_amount": 0
}'Parameters
walletRequired- TRON address receiving the Energy delegation — the wallet that will send USDT.
energyRequired- Energy amount from the current tariffs. Before every order, use GET /v1/public/fee-estimate to calculate the required package; do not choose it at random.
trx_topupOptional- Guaranteed cost coverage. A separate 0.5 TRX fee is deducted from the service balance. The method is selected automatically: 400 Bandwidth for 1 hour or 0.345 TRX sent to the sender wallet.
trx_topup_amountOptional- Use 0.345 when enabled and 0 when disabled. This is the service denomination, not the fee: do not use 0.5 here.
Only these two combinations are valid
price_trx includes only Energy. The 0.5 TRX coverage fee is charged separately.
trx_topup_sent=true means TRX was sent or a Bandwidth order was accepted; delegation may still be in progress. trx_topup_blockchain_tx_id can be null until the transaction hash is available. Your client does not need to poll Netts.
Example response
{
"price_trx": 2.8,
"balance_trx_after": 122.7
}Examples are illustrative; tariff and order prices may differ.