Execute

Submit a relay

Checks the request, quotes it, holds the cost on your balance, then runs the relay in the background. Limit: 100 per minute, shared with batch items.

POST/api/chain_relayers/portal/execute

curl -X POST "https://apiv2.tronergy.io/api/chain_relayers/portal/execute" \
  -H "x-api-key: $TRONERGY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "tron",
    "mode": "sponsored_broadcast",
    "payload": {
      "signed_tx": {
        "txID": "...",
        "raw_data": {},
        "raw_data_hex": "...",
        "signature": [
          "..."
        ]
      }
    },
    "idempotencyKey": "3b6f6c1e-2f7a-4f43-9a55-6a1f5c2d9e10",
    "environment": "live"
  }'

const response = await fetch("https://apiv2.tronergy.io/api/chain_relayers/portal/execute", {
  method: "POST",
  headers: {
    "x-api-key": process.env.TRONERGY_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    chain: "tron",
    mode: "sponsored_broadcast",
    payload: {
      signed_tx: {
        txID: "...",
        raw_data: {},
        raw_data_hex: "...",
        signature: [
          "...",
        ],
      },
    },
    idempotencyKey: "3b6f6c1e-2f7a-4f43-9a55-6a1f5c2d9e10",
    environment: "live",
  }),
});

const data = await response.json();

import os
import requests

response = requests.post(
    "https://apiv2.tronergy.io/api/chain_relayers/portal/execute",
    headers={
        "x-api-key": os.environ["TRONERGY_API_KEY"],
    },
    json={
        "chain": "tron",
        "mode": "sponsored_broadcast",
        "payload": {
            "signed_tx": {
                "txID": "...",
                "raw_data": {},
                "raw_data_hex": "...",
                "signature": [
                    "...",
                ],
            },
        },
        "idempotencyKey": "3b6f6c1e-2f7a-4f43-9a55-6a1f5c2d9e10",
        "environment": "live",
    },
)
data = response.json()

Parameters

chainstringrequired

Always tron.

modestringrequired

delegate_energy, sponsored_broadcast, token_pay, trx_fee_token_pay or sunswap_swap.

payloadRecord<string, unknown>required

Depends on mode, see the table below. Max 64 KB.

idempotencyKeystringrequired

A UUID you generate once per relay. Reuse it only to retry the same relay.

environment"sandbox" | "live"

sandbox or live. Defaults to sandbox.

userAddressstring

Expected sender (T...). If set, the signed transaction's sender must match.

priority"fast" | "cheap"

fast or cheap.

syncboolean

Wait for the result before answering. Not supported for sunswap_swap. Defaults to false.

syncTimeoutMsnumber

How long to wait when sync is true, in ms. Default 5000, max 8000.

Response (202)

{
  "ok": true,
  "operationId": "8d0f6a52-6a3b-4a43-b1b0-7f9c2f0b3c11",
  "status": "pending",
  "estimate": { "estimatedCostNative": "2.950000", "estimatedCostUsd": "0.840000", "unit": "TRX" }
}

Track the relay with Get an operation or the status stream. See Track status.

Payload by mode

Mode	`payload`	Guide
`delegate_energy`	`{ "target_address", "energy_amount", "duration_seconds"? }`. `energy_amount` is a positive integer. `duration_seconds` is `3600` (default) to `2592000`. No other fields.	Rent energy
`sponsored_broadcast`	`{ "signed_tx" }`	Send USDT
`token_pay`, `trx_fee_token_pay`	`{ "fee_signed_tx", "user_signed_tx", "fee_recipient"? }`. If `fee_recipient` is set, the fee transaction must pay exactly that address.	Pay fees in tokens
`sunswap_swap`	Setup step: `{ "session_id", "draft_id", "signed_txs": [{ "id", "tx" }] }`. Swap step: `{ "session_id", "draft_id", "signed_tx" }`.	Swap

Signed transactions are TronWeb transaction objects with txID, raw_data, raw_data_hex and a signature array, sent exactly as the wallet signed them. raw_data_hex is required, txID must be its hash, and raw_data must describe the same transaction, or the request fails with 400 TX_DECODE_FAILED.

Response codes

HTTP	Meaning
`202`	Accepted. The relay runs in the background.
`200`	This `idempotencyKey` was already used. You get the existing operation and its current `status`, even if it failed. Nothing new is created.
`200` with `sync`	Finished: `"settled": true`, a final `status`, and `txHash` when completed.
`202` with `sync`	Still running after the wait: `"settled": false`. Keep polling.

Response (sync, 200)

{ "ok": true, "operationId": "8d0f...", "status": "completed", "settled": true, "txHash": "c0ffee..." }

sunswap_swap responses also include stage, sessionId, nextAction and sessionTerminal.

A repeated key returns the first operation even if the payload differs. To try a failed relay again, sign a fresh transaction and use a new key.

Common errors, all returned before anything is charged or broadcast: 422 Validation failed, 422 INVALID_PAYLOAD, 422 ENERGY_AMOUNT_BELOW_MINIMUM, 400 TX_EXPIRED and other TX_* codes, 400 INSUFFICIENT_SENDER_BALANCE, 422 SIMULATION_REVERTED (the transaction would revert on chain), 422 INSUFFICIENT_BALANCE, 409 IDEMPOTENCY_KEY_CONFLICT, 429. A 502 with operationId and "status": "failed" means the relay could not start and was not broadcast. See Errors.

Execute

Submit a relayCopy Anchor Link

Payload by modeCopy Anchor Link

Response codesCopy Anchor Link

On this page

Submit a relay

Payload by mode

Response codes