Patrocinar comisiones TRC20: TronFuel
Patrocinar la comisión significa que un tercero paga la energy y el bandwidth que consume una transacción de TRON, de modo que la wallet de envío no necesita TRX. Recomendamos TronFuel para ello. El Paymaster de Chaingateway hacía el mismo trabajo dentro de la API y está obsoleto (deprecated): las integraciones existentes siguen funcionando, pero las nuevas no deben usarlo.
¿Por qué una wallet de TRON con tokens pero sin TRX no puede enviarlos?
Sección titulada «¿Por qué una wallet de TRON con tokens pero sin TRX no puede enviarlos?»Una transferencia TRC20 es una llamada a un smart contract. TRON cobra energy y bandwidth por ella, y una dirección paga esos recursos quemando TRX o usando recursos que tiene en staking o que le han delegado. El token en sí nunca paga.
Eso produce una situación con la que toda integración de TRON se topa tarde o temprano. Un cliente deposita USDT en una dirección recién creada. La dirección ahora tiene tokens y nada más. Enviar esos tokens más adelante falla con estado 422 y el mensaje balance is not sufficient, porque no hay TRX para cubrir el coste de recursos. Financiar con TRX cada dirección de depósito por adelantado funciona, pero inmoviliza TRX en direcciones que puede que nunca se usen.
Patrocinar la comisión resuelve esto desde el otro lado. Un tercero paga el coste de recursos, y la wallet envía sus tokens sin tener TRX en ningún momento.
¿Qué debo usar en lugar del Paymaster?
Sección titulada «¿Qué debo usar en lugar del Paymaster?»TronFuel es lo que recomendamos para esto hoy. Alquila energy al por mayor de stakers en lugar de quemar TRX, que es de donde viene el ahorro frente a una quema simple. El contexto está desarrollado en Comisiones de transacción TRC-20 en TRON explicadas.
TronFuel es un servicio independiente. No tiene ningún endpoint dentro de la API de Chaingateway, así que nada en esta documentación describe cómo llamarlo. Siga el enlace anterior para consultar su propia documentación.
¿Sigue disponible el Paymaster?
Sección titulada «¿Sigue disponible el Paymaster?»El Paymaster de Chaingateway hacía el mismo trabajo dentro de la API: cubría bandwidth y energy para que una wallet no necesitara TRX antes de enviar tokens TRC20, y facturaba el coste contra un saldo de crédito de su cuenta.
El servicio está obsoleto (deprecated). Las integraciones que ya llaman a los endpoints de Paymaster siguen funcionando, y los endpoints se documentan a continuación por esa razón. No construya integraciones nuevas sobre ellos.
| Endpoint | Función |
|---|---|
POST /api/v2/tron/paymaster | Crear una solicitud de transacción patrocinada |
GET /api/v2/tron/paymaster | Listar sus solicitudes y su estado |
GET /api/v2/tron/paymaster/{id} | Leer una solicitud |
POST /api/v2/tron/paymaster/estimate | Estimar energy, bandwidth y comisión |
GET /api/v2/tron/paymaster/balance | Leer su saldo de crédito restante |
Estimar primero el coste
Sección titulada «Estimar primero el coste»La energy y el bandwidth que necesita una transacción dependen del tipo de transacción y del contrato al que llama, así que el importe no es fijo. POST /api/v2/tron/paymaster/estimate recibe el mismo cuerpo que la propia solicitud y devuelve lo que costaría la transacción.
curl --request POST\ --url https://app.chaingateway.io/api/v2/tron/paymaster/estimate\ --header 'Accept: application/json'\ --header 'Content-Type: application/json'\ --header 'Authorization: Bearer YOUR_API_TOKEN'\ --data '{ "type": "TRC20", "from": "TLkkCeNdJKPNUwucdro84WjswkzM62LCTH", "to": "TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp", "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "amount": "1"}'{ "status": 200, "ok": true, "message": "Successfully estimated the fees", "data": { "energy_consumption": 32000, "bandwidth_consumption": 368, "paymaster_fee": 0.15 }}La comisión se descuenta del saldo de crédito cuando la solicitud se liquida. Si el saldo no la cubre, la solicitud falla. GET /api/v2/tron/paymaster/balance devuelve lo que queda.
Crear una solicitud patrocinada
Sección titulada «Crear una solicitud patrocinada»type acepta TRX, TRC10, TRC20 y TRC721. Junto con from, to y amount es obligatorio. Para TRC20 y TRC721 también se indica contractaddress, y para TRC721 y TRC10 el tokenid. La firma funciona como en el resto de la API: password para una dirección de Chaingateway protegida con contraseña, privatekey en caso contrario. Un callback_url opcional recibe el resultado.
curl --request POST\ --url https://app.chaingateway.io/api/v2/tron/paymaster\ --header 'Accept: application/json'\ --header 'Content-Type: application/json'\ --header 'Authorization: Bearer YOUR_API_TOKEN'\ --data '{ "type": "TRC20", "from": "TLkkCeNdJKPNUwucdro84WjswkzM62LCTH", "to": "TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp", "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "amount": "1", "password": "test123", "callback_url": "https://example.com/callback"}'La respuesta no es un hash de transacción, sino el identificador de la solicitud:
{ "status": 200, "ok": true, "message": "Successfully created paymaster request", "data": { "id": "9c72d676-8180-4cd2-a406-f0f1cd097506" }}Seguir una solicitud
Sección titulada «Seguir una solicitud»Consulte GET /api/v2/tron/paymaster/{id} con ese identificador, o liste todas las solicitudes con GET /api/v2/tron/paymaster. El campo status pasa por pending mientras la solicitud espera, processing mientras la transacción está en camino y completed cuando se ha liquidado. Un fallo se lee failed - [reason], con el motivo escrito después del guion. El hash de la transacción resultante aparece en el registro cuando la transacción ha terminado.
{ "id": "9cfbfcaf-68b2-47e9-bf55-5b6b4875e84d", "type": "TRC20", "from": "THG9nncwASg3ub5rvVquocAHwwQbnKZxpH", "to": "TPUjdnMrS7XDUFp5W6zgh4QDCW34nXa2x1", "contract_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "amount": "200", "token_id": null, "transaction_hash": "80a223e0cb20ef692fbd23d3cbaf3cc1dfa2b9667aaef70c7da8ca8f707ec28b", "status": "success", "used_credits": "2.178413", "callback_url": "https://api.chaingateway.io/receiver/webhooks/tron", "created_at": "2024-09-11T15:28:57.000000Z"}¿Puedo poner TRX en staking en lugar de pagar por transacción?
Sección titulada «¿Puedo poner TRX en staking en lugar de pagar por transacción?»Si el TRX ya es suyo, puede ponerlo en staking una vez y reutilizar los recursos en lugar de pagar por transacción. POST /api/v2/tron/freeze pone TRX en staking para energy o bandwidth, POST /api/v2/tron/delegate entrega esos recursos a otra dirección, y POST /api/v2/tron/undelegate y POST /api/v2/tron/unfreeze revierten ambos pasos. Una sola dirección con staking puede abastecer a las direcciones de depósito que dependen de ella, que es el patrón adecuado para un flujo de pagos con muchas direcciones receptoras.
Los cuatro endpoints de staking comparten la misma forma de cuerpo. Los campos address, amount y resource son obligatorios, y resource es BANDWIDTH o ENERGY. delegate y undelegate añaden un receiver obligatorio. Como en toda la API, se firma con password o privatekey.
curl --request POST\ --url https://app.chaingateway.io/api/v2/tron/freeze\ --header 'Accept: application/json'\ --header 'Content-Type: application/json'\ --header 'Authorization: Bearer YOUR_API_TOKEN'\ --data '{ "address": "TLkkCeNdJKPNUwucdro84WjswkzM62LCTH", "amount": 100, "resource": "ENERGY", "password": "test123"}'Una llamada correcta devuelve data.result: true y el txid de la transacción de staking. Del archivo OpenAPI se aplican dos reglas a la delegación: el saldo debe estar congelado antes de poder delegarse, y el receptor debe ser distinto de la dirección propietaria. Una llamada fallida devuelve el estado 422 con el mensaje del nodo, por ejemplo no frozenBalance(Energy) cuando se descongela más de lo que se puso en staking, o delegated Resource does not exist cuando se anula la delegación de algo que nunca se delegó. El modelo de recursos de TRON documenta cómo el TRX en staking se convierte en energy y bandwidth.
¿Qué opción se ajusta a mi integración?
Sección titulada «¿Qué opción se ajusta a mi integración?»La tabla compara las opciones según lo que necesitan y lo que cuestan.
| Opción | Qué necesita | Modelo de coste | Estado |
|---|---|---|---|
| Financiar cada dirección con TRX | TRX en cada dirección de depósito | El TRX se quema en cada transacción | funciona, inmoviliza TRX |
| TronFuel | el servicio independiente TronFuel, fuera de la API de Chaingateway | se alquila energy en lugar de quemar TRX | recomendado |
| Staking y delegación | TRX que pueda bloquear | el TRX en staking aporta los recursos en lugar de quemarse | funciona |
| Paymaster | saldo de crédito en su cuenta de Chaingateway | la comisión se descuenta del saldo de crédito | obsoleto |
Compruebe el saldo de TRX de una dirección con GET /api/v2/tron/balances/{address} antes de enviar. Una dirección sin TRX y sin recursos delegados falla con el mensaje balance is not sufficient indicado arriba.
El envío de la transferencia en sí se explica en Crear transacciones de tokens TRC20.
Fuentes
Sección titulada «Fuentes»- TRON resource model define energy, bandwidth, staking y delegación.
- TRC20 protocol interface describe las funciones del contrato a las que llama una transferencia.