API REST v2Documentazione aggiornata il 2 agosto 2026

API TRON Energy Rental: automatizza i trasferimenti USDT TRC-20

Integra l'API v2 per quotare, creare e monitorare gli ordini di noleggio di TRON Energy in modo programmatico. Paga on-chain o dal tuo saldo TronBid e riduci i TRX bruciati dalle chiamate con contratto intelligente.

Preventivi in tempo reale e catalogo dei pacchetti
Pagamento on-chain o a saldo
Ordini idempotenti e polling sullo stato

Ottieni l'accesso all'API Apri Avvio rapido Noleggia energia senza API Calcolare il fabbisogno energetico

In questa pagina

TRON Energy Rental API: panoramica e casi d'uso

L'API Quick Rent è un modo per noleggiare TRON Energy automaticamente, senza lavoro manuale. L'energia rende i trasferimenti USDT (TRC-20) e altre chiamate di contratti intelligenti più economici rispetto alla masterizzazione di TRX.

In parole povere: il tuo programma (un sito, un bot o un servizio) acquista energia da solo, esattamente quando è necessario, ad esempio prima di ogni trasferimento USDT effettuato dal tuo cliente.

Pensa a un distributore automatico: controlli il prezzo, inserisci i soldi, ricevi il tuo articolo. L'API è lo stesso insieme di pulsanti: solo il tuo programma li preme.

1
Chiedi un prezzo
Il tuo programma chiede all'API quanto costa il pacchetto energetico necessario in questo momento.
2
Crea un ordine e paga
Il tuo programma crea un ordine e lo paga, inviando TRX all'indirizzo indicato o addebitando il tuo saldo TronBid.
3
Ottieni l'energia
Nel giro di pochi secondi l'energia appare sul portafoglio di destinazione e gli USDT possono essere inviati a un prezzo inferiore.

Importante: l'API è uno strumento per uno sviluppatore. Per usarlo, qualcuno deve scrivere il codice che invia le richieste.

Se non c'è nessuno che scriva il codice, usa l'acquisto di energia già pronto sul sito (Quick Rent) o il bot di Telegram @tronbid. Stesso risultato, ma fatto manualmente.

Quickstart: da zero all'energia

Un esempio end-to-end completo sullo scenario più semplice (on-chain). Quattro passi e l'energia è nel portafoglio.

Di seguito è riportato cosa succede in ogni passaggio e cosa restituisce l'API. Inserisci la chiave API, gli indirizzi e l'ID dell'ordine.

1
Passaggio 1. Ottieni un prezzo: POST / preventivo
Invia la quantità di energia e la durata. Ottieni indietro price_trx e per quanti secondi è bloccato.
2
Passaggio 2. Crea un ordine: POST /orders
Invia il pacco, la tua idempotency_key e il payer_address. Ottieni pay_address (dove pagare), amount_trx (quanto) e scade_at (fino a quando).
3
Passaggio 3. Paga
Invia esattamente amount_trx TRX a pay_address dal tuo payer_address. È un semplice trasferimento TRON.
4
Passaggio 4. Attendi l'energia: OTTIENI /orders/:id
Esegui il polling sullo stato ogni paio di secondi finché non viene delegato. Ciò significa che l’energia è delegata al portafoglio: fatto.

Risposta

json

{
  "price_trx": "3.200000",
  "available": true,
  "save_percent": 62,
  "expires_in_sec": 30
}

Risposta (sulla catena)

json

{
  "id": "uuid",
  "status": "pending_payment",
  "payment_mode": "onchain",
  "pay_address": "TDeposit...",
  "amount_trx": "3.200000",
  "energy_amount": 131000,
  "duration_minutes": 15,
  "expires_at": "2026-04-29T13:15:00.000Z",
  "qr_payload": "tron:TDeposit...?amount=3.200000",
  "duplicate": false,
  "target_address": "TTarget..."
}

arricciatura

bash

# poll every 3s until the order is done
while true; do
  STATUS=$(curl -sS "$BASE_URL/api/v2/quick-rent/orders/$ORDER_ID" \
    -H "Authorization: Bearer $API_KEY" | jq -r .status)
  echo "status: $STATUS"
  case "$STATUS" in
    delegated|failed|expired|cancelled) break ;;
  esac
  sleep 3
done

Risposta

json

{
  "id": "uuid",
  "status": "delegated",
  "payment_mode": "onchain",
  "amount_trx": "3.200000",
  "energy_amount": 131000,
  "effective_energy_amount": 131000,
  "duration_minutes": 15,
  "pay_address": "TDeposit...",
  "payer_address": "TPayer...",
  "target_address": "TTarget...",
  "error_code": null,
  "error_message": null
}

Glossario

Brevi spiegazioni delle parole utilizzate in questa documentazione.

Energia: Il “carburante” della rete Tron per le operazioni di smart-contract. Se non ce n'è abbastanza, la rete brucia invece TRX, il che è più costoso. Noleggiare l’energia fa risparmiare denaro.
TRX: La moneta nativa della rete TRON. Paga il noleggio dell'energia e le tariffe di rete.
USDT TRC-20: Una stablecoin (dollaro) su TRON. Inviarlo è una chiamata smart-contract che necessita di energia.
Chiave API: La tua password segreta per l'accesso all'API. Inviato con ogni richiesta. Tienilo solo sul server.
Punto finale: Un "pulsante" di indirizzo specifico dell'API in cui il tuo programma invia una richiesta (ad esempio /quote - ottieni un prezzo).
OTTIENI / PUBBLICA: Tipi di richiesta. GET significa "basta chiedere/leggere dati"; POST significa "eseguire un'azione" (creare un ordine, calcolare un prezzo).
Gettone al portatore: Come passi la chiave API: l'intestazione recita Autorizzazione: Portatore YOUR_KEY.
Pagamento in catena: Pagare un ordine con un semplice trasferimento TRX all'indirizzo indicato: funziona immediatamente, non c'è nulla da abilitare.
Pagamento del saldo: Pagare addebitando il saldo del tuo conto TronBid. Più veloce, ma deve prima essere abilitato per la tua chiave.
Delegazione: Consegna temporanea dell'energia noleggiata al portafoglio target per il periodo di noleggio (ad esempio 15 o 60 minuti).
Sondaggio: Richiedere nuovamente lo stato dell'ordine periodicamente (ogni paio di secondi) fino a quando non viene delegato o termina con un errore.
chiave_idempotenza: Il tuo ID ordine univoco. Se una richiesta viene inviata due volte, l'API restituisce lo stesso ordine invece di crearne uno nuovo: protezione contro il doppio pagamento.

Prima di iniziare

Cosa preparare prima di fare la prima richiesta.

1
Ottieni una chiave API
Invia un messaggio a @tronbid su Telegram: riceverai una chiave associata al tuo account TronBid. Le richieste non passeranno senza di essa.
2
Avere un portafoglio TRON target
Decidi l'indirizzo (target_address) che necessita di energia. Di solito è il portafoglio da cui i tuoi clienti inviano USDT.
3
Scegli un pacchetto dal catalogo
L'energia viene venduta in pacchetti (solitamente 65000 o 131000 energia per 15 o 60 minuti). Ottieni l'elenco attivo dall'endpoint del catalogo, senza bisogno di autenticazione.
4
Preparare il pagamento
Per on-chain: un portafoglio con TRX per pagare. Per il pagamento del saldo: un conto TronBid finanziato e la modalità saldo abilitata.

URL di base dell'API di produzione

L'API Quick Rent consente al tuo servizio di noleggiare TRON Energy automaticamente, quindi i trasferimenti USDT TRC-20 e altre chiamate con contratto intelligente costano meno della masterizzazione di TRX.

Tutti gli endpoint condividono un URL di base.

URL di base (produzione)

http

https://tronbid.com/api/v2/quick-rent

Autorizzazione

Ogni richiesta deve includere la tua chiave API come token Bearer nell'intestazione Authorization.

Conserva la chiave solo lato server (backend, segreti CI). Non spedirlo mai nel codice frontend o nei repository pubblici. La chiave è vincolata ad un singolo account TronBid (il portafoglio impostato al momento dell'accesso); i pagamenti del saldo possono essere prelevati solo da quel conto.

Se superi il limite di velocità, l'API risponde con HTTP 429.

http

Authorization: Bearer <API_KEY>

Modalità di pagamento

Esistono due modi per pagare un ordine. On-chain è l'impostazione predefinita e non necessita di configurazione. Il pagamento del saldo è facoltativo e deve essere abilitato per la tua chiave.

Senza attivazione, una richiesta con payment_mode: balance restituisce 403 BALANCE_PAYMENT_NOT_ENABLED. Per abilitarlo, contattare il supporto TronBid.

Mode	Come abilitare	Pagamento
`on-chain`	Predefinito: ometti payment_mode (o "onchain")	Invia TRX a pay_address da payer_address
`balance`	payment_mode: saldo + abilitato per la tua chiave	Addebitato sul tuo saldo TronBid TRX

Catalogo dei pacchetti

Energy_Amount e Duration_Minuti devono corrispondere a un pacchetto Quick Rent attivo, in genere 65.000 o 131.000 energia e 15 o 60 minuti.

Recupera il catalogo corrente in qualsiasi momento (non è richiesta alcuna autenticazione):

Ottieni il catalogo attivo (nessuna autenticazione)

bash

curl -sS https://tronbid.com/api/public/quick-rent/skus

Flusso a catena

Passaggio 1: PUBBLICA/preventivo per conoscere il prezzo. Passaggio 2: INVIA /orders per creare l'ordine e ricevere pay_address, amount_trx e scade_at. Passaggio 3: invia esattamente amount_trx TRX a pay_address dal tuo payer_address. Passaggio 4: interroga GET /orders/:id finché lo stato non viene delegato (o non riuscito/scaduto/annullato).

target_address è facoltativo: se omesso, l'energia è delegata a payer_address.

È consentito un solo ordine aperto sulla catena (pagamento_in sospeso) per indirizzo_pagatore alla volta; altrimenti riceverai 409 PENDING_PAYMENT_INTENT_EXISTS. In caso di pagamento insufficiente/eccessivo l'energia finale può differire: controlla Effective_energy_amount in GET /orders/:id.

Richiedi corpo

json

{
  "energy_amount": 131000,
  "duration_minutes": 15,
  "idempotency_key": "your-unique-key-001",
  "payer_address": "TPayerWalletXXXXXXXXXXXXXXXXXXXXXX",
  "target_address": "TTargetWalletXXXXXXXXXXXXXXXXXXXXX"
}

Risposta

json

{
  "id": "uuid",
  "status": "pending_payment",
  "payment_mode": "onchain",
  "pay_address": "TDeposit...",
  "amount_trx": "3.200000",
  "energy_amount": 131000,
  "duration_minutes": 15,
  "expires_at": "2026-04-29T13:15:00.000Z",
  "qr_payload": "tron:TDeposit...?amount=3.200000",
  "duplicate": false,
  "target_address": "TTarget..."
}

Flusso di equilibrio

Passaggio 1: OTTIENI /balance per controllare il tuo TRX. Passaggio 2: POST/preventivo per il prezzo. Passaggio 3: POST/ordini con modalità_pagamento: saldo da addebitare e avvio della delega. Passaggio 4: poll GET /orders/:id fino alla delega (in caso di errore di delega la delega diventa fallita e TRX viene rimborsato sul tuo saldo).

payer_address non è necessario: paga l'account collegato alla tua chiave API. L'energy_amount nella risposta può essere superiore allo SKU ordinato (bonus matrice prezzo).

Richiedi corpo

json

{
  "energy_amount": 131000,
  "duration_minutes": 15,
  "idempotency_key": "your-unique-key-balance-001",
  "payment_mode": "balance",
  "target_address": "TTargetWalletXXXXXXXXXXXXXXXXXXXXX"
}

Risposta

json

{
  "id": "uuid",
  "status": "delegating",
  "payment_mode": "balance",
  "pay_address": null,
  "amount_trx": "3.200000",
  "energy_amount": 132310,
  "duration_minutes": 15,
  "expires_at": null,
  "qr_payload": null,
  "duplicate": false,
  "target_address": "TTarget..."
}

Stati degli ordini

Ogni ordine passa attraverso questi stati. Sondaggio GET /orders/:id per seguirlo.

Status	Significato
`pending_payment`	In attesa del pagamento in catena
`delegating`	Pagamento ricevuto o saldo addebitato; delegazione in corso
`delegated`	Energia delegata
`cancelled`	Annullato prima del pagamento (on-chain)
`expired`	La finestra di pagamento in catena è scaduta
`failed`	Errore (per il saldo, TRX viene rimborsato)

Idempotenza

idempotency_key (8–128 caratteri) è un ID ordine univoco dalla tua parte. La ripetizione di POST /orders con la stessa chiave (per lo stesso client API) restituisce lo stesso ordine con "duplicato": true.

Non riutilizzare una idempotency_key in diverse modalità di pagamento (onchain o saldo): restituisce 409 IDEMPOTENCY_PAYMENT_MODE_MISMATCH.

Calcola i fabbisogni di noleggio di TRON Energy

Stimare la quantità di energia necessaria a un indirizzo per un trasferimento. Passa il portafoglio del destinatario e indica se contiene già USDT.

POST/api/v2/quick-rent/calculator

Parametri

Parametro	Type	Descrizione	Example
`indirizzo_portafoglio`	string	Indirizzo TRON da analizzare	`TXXXXXXXX...XXXX`
`has_usdt`	boolean \| null	Se il destinatario detiene già USDT (influisce sull'energia). vero, falso o omettere.	`true`

Richiedi corpo

json

{
  "wallet_address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "has_usdt": true
}

arricciatura

bash

curl -sS -X POST "$BASE_URL/api/v2/quick-rent/calculator" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"wallet_address":"TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX","has_usdt":true}'

Ottieni un preventivo di noleggio TRON Energy

Restituisce il prezzo corrente per un pacchetto: price_trx, disponibilità, save_percent e per quanto tempo è valido il preventivo (expires_in_sec).

POST/api/v2/quick-rent/quote

Parametri

Parametro	Type	Descrizione	Example
`energia_quantità`	int	Quantità di energia dal catalogo attivo	`131000`
`durata_minuti`	int	Durata noleggio da catalogo	`15`

Risposta

json

{
  "price_trx": "3.200000",
  "available": true,
  "save_percent": 62,
  "expires_in_sec": 30
}

arricciatura

bash

export BASE_URL="https://tronbid.com"
export API_KEY="your_api_key"

curl -sS -X POST "$BASE_URL/api/v2/quick-rent/quote" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"energy_amount":131000,"duration_minutes":15}'

Crea un ordine di noleggio TRON Energy

Crea un ordine di noleggio. Per la catena, passa payer_address e paga l'importo restituito amount_trx a pay_address. Per saldo, aggiungi payment_mode: saldo e l'importo verrà addebitato immediatamente sul conto collegato.

target_address è facoltativo (il valore predefinito è payer_address). Attenzione alle regole 409: un ordine aperto sulla catena per pagatore e nessuna delega Quick Rent attiva già sul bersaglio (ACTIVE_DELEGATION_EXISTS).

POST/api/v2/quick-rent/orders

Parametri

Parametro	Type	Descrizione	Example
`energia_quantità`	int	Quantità di energia dal catalogo	`131000`
`durata_minuti`	int	Durata noleggio da catalogo	`15`
`chiave_idempotenza`	string	Il tuo ID ordine univoco (8-128 caratteri)	`partner-onchain-001`
`modalità_pagamento`	string	Facoltativo. "onchain" (predefinito) o "balance".	`balance`
`indirizzo_pagatore`	string	On-chain: portafoglio che invia TRX. Non necessario per l'equilibrio.	`TPayer...`
`indirizzo_destinazione`	string	Facoltativo. Portafoglio che riceve energia (predefinito su payer_address).	`TTarget...`

Risposta (sulla catena)

json

{
  "id": "uuid",
  "status": "pending_payment",
  "payment_mode": "onchain",
  "pay_address": "TDeposit...",
  "amount_trx": "3.200000",
  "energy_amount": 131000,
  "duration_minutes": 15,
  "expires_at": "2026-04-29T13:15:00.000Z",
  "qr_payload": "tron:TDeposit...?amount=3.200000",
  "duplicate": false,
  "target_address": "TTarget..."
}

Risposta (saldo)

json

{
  "id": "uuid",
  "status": "delegating",
  "payment_mode": "balance",
  "pay_address": null,
  "amount_trx": "3.200000",
  "energy_amount": 132310,
  "duration_minutes": 15,
  "expires_at": null,
  "qr_payload": null,
  "duplicate": false,
  "target_address": "TTarget..."
}

cURL (sulla catena)

bash

curl -sS -X POST "$BASE_URL/api/v2/quick-rent/orders" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "energy_amount": 131000,
    "duration_minutes": 15,
    "idempotency_key": "partner-onchain-001",
    "payer_address": "TPayer...",
    "target_address": "TTarget..."
  }'

arricciatura (equilibrio)

bash

curl -sS -X POST "$BASE_URL/api/v2/quick-rent/orders" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "energy_amount": 131000,
    "duration_minutes": 15,
    "idempotency_key": "partner-balance-001",
    "payment_mode": "balance",
    "target_address": "TTarget..."
  }'

Ottieni lo stato dell'ordine

Restituisce lo stato corrente, la modalità_pagamento, gli importi, gli indirizzi e il codice_errore/messaggio_errore se qualcosa non è riuscito. Effective_energy_amount riflette l'effettiva energia delegata dopo il pagamento insufficiente/eccessivo.

GET/api/v2/quick-rent/orders/:id

Parametri

Parametro	Type	Descrizione	Example
`id`	string	ID ordine (parametro percorso)	`uuid`

Risposta

json

{
  "id": "uuid",
  "status": "delegated",
  "payment_mode": "onchain",
  "amount_trx": "3.200000",
  "energy_amount": 131000,
  "effective_energy_amount": 131000,
  "duration_minutes": 15,
  "pay_address": "TDeposit...",
  "payer_address": "TPayer...",
  "target_address": "TTarget...",
  "error_code": null,
  "error_message": null
}

arricciatura

bash

curl -sS "$BASE_URL/api/v2/quick-rent/orders/$ORDER_ID" \
  -H "Authorization: Bearer $API_KEY"

Annulla ordine

Annulla un ordine ancora in sospeso_pagamento (solo on-chain). Una volta delegata l'energia, l'ordine non potrà più essere annullato.

POST/api/v2/quick-rent/orders/:id/cancel

Parametri

Parametro	Type	Descrizione	Example
`id`	string	ID ordine (parametro percorso)	`uuid`

arricciatura

bash

curl -sS -X POST "$BASE_URL/api/v2/quick-rent/orders/$ORDER_ID/cancel" \
  -H "Authorization: Bearer $API_KEY"

Cambia pagatore

Modifica il portafoglio di pagamento per un ordine on-chain pendente_pagamento: utile se il cliente decide di pagare da un portafoglio diverso prima di inviare TRX.

POST/api/v2/quick-rent/orders/:id/set-payer

Parametri

Parametro	Type	Descrizione	Example
`id`	string	ID ordine (parametro percorso)	`uuid`
`indirizzo_pagatore`	string	Nuovo portafoglio a pagamento	`TNewPayer...`

arricciatura

bash

curl -sS -X POST "$BASE_URL/api/v2/quick-rent/orders/$ORDER_ID/set-payer" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payer_address":"TNewPayer..."}'

Controlla il saldo API TronBid

Restituisce il saldo TRX dell'account TronBid collegato alla tua chiave API (il tuo saldo in-app, non un portafoglio on-chain). Richiede l'intestazione di autorizzazione.

GET/api/v2/quick-rent/balance

Risposta

json

{ "balance_trx": "150.500000" }

arricciatura

bash

curl -sS "$BASE_URL/api/v2/quick-rent/balance" \
  -H "Authorization: Bearer $API_KEY"

Codici di errore

Gli errori restituiscono uno stato HTTP e un campo di errore. Ecco quelli che potresti incontrare.

HTTP	error	Quando
400	`Invalid body`	JSON o campi non validi
400	`INVALID_SKU / SKU_INACTIVE`	Pacchetto non disponibile
400	`INVALID_PAYER_ADDRESS / INVALID_TARGET_ADDRESS`	Indirizzo TRON non valido
400	`INSUFFICIENT_BALANCE`	TRX insufficiente in equilibrio (modalità equilibrio)
401	`Unauthorized`	Chiave API mancante o non valida
403	`BALANCE_PAYMENT_NOT_ENABLED`	Pagamento del saldo non abilitato per la tua chiave
409	`PENDING_PAYMENT_INTENT_EXISTS`	Esiste già un ordine on-chain aperto per questo pagatore
409	`ACTIVE_DELEGATION_EXISTS`	Target ha già una delegazione Quick Rent attiva
409	`POOL_ENERGY_INSUFFICIENT`	Nessuna energia gratuita per la piscina in questo momento
409	`IDEMPOTENCY_PAYMENT_MODE_MISMATCH`	Stessa idempotency_key con una modalità di pagamento diversa
429	`Too Many Requests`	Limite di tariffa
503	`—`	Servizio momentaneamente non disponibile, riprova più tardi

Se qualcosa va storto

Situazioni comuni e cosa fare, in parole povere.

Ho pagato ma l'ordine è bloccato in sospeso_pagamento

Assicurati che l'importo trasferito sia esattamente uguale a amount_trx e che i fondi siano andati a pay_address dall'esatto payer_address. Il trasferimento deve arrivare prima della scadenza_at. Lo stato di solito si aggiorna entro un minuto dalla conferma della rete: continua a eseguire il polling GET /orders/:id.

Lo stato è diventato fallito: di cosa si tratta?

La delega non ha avuto successo. Per i pagamenti a saldo, il TRX viene automaticamente restituito al tuo saldo. Il motivo è in error_code e error_message di GET /orders/:id. Puoi creare un nuovo ordine.

Errore 409 PENDING_PAYMENT_INTENT_EXISTS

Questo payer_address ha già un ordine on-chain non pagato. Pagalo, attendi che scada (expires_at) o annullalo tramite /orders/:id/cancel, quindi creane uno nuovo.

Errore 403 BALANCE_PAYMENT_NOT_ENABLED

Il pagamento del saldo non è abilitato per la tua chiave. Contatta il supporto TronBid per attivarlo o utilizza on-chain (impostazione predefinita).

Errore 429 Troppe richieste

Troppe richieste in poco tempo. Ridurre la frequenza di polling (ad esempio una volta ogni 3 secondi) e riprovare più tardi.

Ho ricevuto meno energia di quella che avevo ordinato

In caso di pagamento insufficiente/eccessivo in catena, l'importo finale cambia. Controlla Effective_energy_amount in GET /orders/:id — questa è l'energia effettivamente delegata.

Supporto per l'integrazione dell'API TRON Energy

Hai bisogno dell'accesso API, di limiti più elevati o del pagamento del saldo abilitato? Contattaci e ti aiuteremo.

Accesso API e pagamento del saldoTelegramma @tronbid

E-mailsupport@tronbid.com