Comisiones TRC20: TronFuel y Paymaster

El problema: los tokens sin TRX no se pueden mover

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.

TronFuel es la vía recomendada

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 Ahorre hasta un 60 % en comisiones de transacciones TRC-20 en TRON.

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.

El Paymaster está abandonado

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á abandonado (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 /v2/tron/paymaster	Crear una solicitud de transacción patrocinada
GET /v2/tron/paymaster	Listar sus solicitudes y su estado
GET /v2/tron/paymaster/{id}	Leer una solicitud
POST /v2/tron/paymaster/estimate	Estimar energy, bandwidth y comisión
GET /v2/tron/paymaster/balance	Leer su saldo de crédito restante

Estimar el coste primero

Cuánta energy y bandwidth necesita una transacción depende del tipo de transacción y del contrato al que llama, así que el importe no es fijo. POST /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://api.chaingateway.io/v2/tron/paymaster/estimate\
  --header 'Accept: application/json'\
  --header 'content-type: application/json'\
  --header 'Authorization: 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 una vez que la solicitud se liquida. Un saldo que no la cubra hace que la solicitud falle. GET /v2/tron/paymaster/balance devuelve lo que queda.

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 envía contractaddress, 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://api.chaingateway.io/v2/tron/paymaster\
  --header 'Accept: application/json'\
  --header 'content-type: application/json'\
  --header 'Authorization: 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 id de la solicitud:

{
  "status": 200,
  "ok": true,
  "message": "Successfully created paymaster request",
  "data": {
    "id": "9c72d676-8180-4cd2-a406-f0f1cd097506"
  }
}

Seguir una solicitud

Consulte GET /v2/tron/paymaster/{id} con ese id, o liste todas las solicitudes con GET /v2/tron/paymaster. El campo status pasa por pending mientras la solicitud espera, processing mientras la transacción está en camino, y completed una vez liquidada. Un fallo se lee como failed - [reason], con el motivo detallado tras el guion. El hash de la transacción resultante aparece en el registro una vez completada la transacción.

{
  "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"
}

El staking como tercera opción

Si el TRX es suyo de todos modos, puede hacer staking una vez y reutilizar los recursos en lugar de pagar por transacción. POST /v2/tron/freeze pone TRX en staking para obtener energy o bandwidth, POST /v2/tron/delegate cede esos recursos a otra dirección, y POST /v2/tron/undelegate y POST /v2/tron/unfreeze revierten ambos pasos. Una única dirección en staking puede abastecer a las direcciones de depósito que hay detrás, que es el patrón que encaja con un flujo de pagos con muchas direcciones receptoras.

Enviar la transferencia en sí se cubre en Crear transacciones de tokens TRC20 en TRON.