Batches

A batch is many relays of one mode, run in the background. Each item becomes a normal operation. See Batch.

Submit a batch

Accepts up to 25 items by default (your account may allow up to 100). Limit: 10 calls per minute, and each item uses 1 of your 100 execute points.

POST/api/chain_relayers/portal/batch

curl -X POST "https://apiv2.tronergy.io/api/chain_relayers/portal/batch" \
  -H "x-api-key: $TRONERGY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "tron",
    "mode": "delegate_energy",
    "environment": "live",
    "batchIdempotencyKey": "0b6a3c1e-1d2f-4c55-8f0a-2b9e7d4c6a11",
    "items": [
      {
        "payload": {
          "target_address": "TAddressOnexxxxxxxxxxxxxxxxxxxxxxx",
          "energy_amount": 65000
        }
      },
      {
        "payload": {
          "target_address": "TAddressTwoxxxxxxxxxxxxxxxxxxxxxxx",
          "energy_amount": 65000
        }
      }
    ]
  }'

const response = await fetch("https://apiv2.tronergy.io/api/chain_relayers/portal/batch", {
  method: "POST",
  headers: {
    "x-api-key": process.env.TRONERGY_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    chain: "tron",
    mode: "delegate_energy",
    environment: "live",
    batchIdempotencyKey: "0b6a3c1e-1d2f-4c55-8f0a-2b9e7d4c6a11",
    items: [
      {
        payload: {
          target_address: "TAddressOnexxxxxxxxxxxxxxxxxxxxxxx",
          energy_amount: 65000,
        },
      },
      {
        payload: {
          target_address: "TAddressTwoxxxxxxxxxxxxxxxxxxxxxxx",
          energy_amount: 65000,
        },
      },
    ],
  }),
});

const data = await response.json();

import os
import requests

response = requests.post(
    "https://apiv2.tronergy.io/api/chain_relayers/portal/batch",
    headers={
        "x-api-key": os.environ["TRONERGY_API_KEY"],
    },
    json={
        "chain": "tron",
        "mode": "delegate_energy",
        "environment": "live",
        "batchIdempotencyKey": "0b6a3c1e-1d2f-4c55-8f0a-2b9e7d4c6a11",
        "items": [
            {
                "payload": {
                    "target_address": "TAddressOnexxxxxxxxxxxxxxxxxxxxxxx",
                    "energy_amount": 65000,
                },
            },
            {
                "payload": {
                    "target_address": "TAddressTwoxxxxxxxxxxxxxxxxxxxxxxx",
                    "energy_amount": 65000,
                },
            },
        ],
    },
)
data = response.json()

Parameters

chainstringrequired

Always tron.

modestringrequired

delegate_energy, sponsored_broadcast, token_pay or trx_fee_token_pay. sunswap_swap cannot be batched.

environment"sandbox" | "live"

sandbox or live. Defaults to sandbox.

priority"fast" | "cheap"

fast or cheap.

batchIdempotencyKeystringrequired

A UUID for this batch. Resending it with the same items returns the existing batch.

itemsArray<{ payload: Record<string, unknown>; idempotencyKey?: string; userAddress?: string }>required

Each item: payload (same as Execute, max 64 KB), optional idempotencyKey (unique, max 200 chars, must not start with batch:) and optional userAddress. 4 MB total.

Response (202)

{ "ok": true, "batchId": "5e1d...", "status": "accepted", "itemCount": 2 }

200 means you resent a known batchIdempotencyKey. Items are checked and quoted after the batch is accepted; an item that fails those checks shows up in failures on Get a batch with the same code Execute would return.

The whole body must be at most 8 MB (413 BODY_TOO_LARGE). Other errors: 422 VALIDATION_FAILED, 422 BATCH_TOO_LARGE, 422 UNSUPPORTED_MODE, 409 IDEMPOTENCY_KEY_REUSED, 429 RATE_LIMITED.

Get a batch

Returns dispatch status and every item's operation.

GET/api/chain_relayers/portal/batch/:id

curl "https://apiv2.tronergy.io/api/chain_relayers/portal/batch/5e1d7c2a-4b3f-4e9a-8d1c-2f6a9b0e3d77" \
  -H "x-api-key: $TRONERGY_API_KEY"

const response = await fetch("https://apiv2.tronergy.io/api/chain_relayers/portal/batch/5e1d7c2a-4b3f-4e9a-8d1c-2f6a9b0e3d77", {
  method: "GET",
  headers: {
    "x-api-key": process.env.TRONERGY_API_KEY,
  },
});

const data = await response.json();

import os
import requests

response = requests.get(
    "https://apiv2.tronergy.io/api/chain_relayers/portal/batch/5e1d7c2a-4b3f-4e9a-8d1c-2f6a9b0e3d77",
    headers={
        "x-api-key": os.environ["TRONERGY_API_KEY"],
    },
)
data = response.json()

Parameters

idstringrequiredpath

Batch ID.

Response

{
  "ok": true,
  "batch": {
    "id": "5e1d...",
    "status": "dispatched",
    "chain": "tron",
    "mode": "delegate_energy",
    "environment": "live",
    "itemCount": 2,
    "aggregateEstimate": { "estimatedCostUsd": "1.68", "unit": "TRX", "coveredItems": 2 },
    "rollup": { "itemsDispatched": 2, "itemsCompleted": 1, "itemsFailed": 0 },
    "createdAt": "2026-10-21T10:00:00.000Z",
    "updatedAt": "2026-10-21T10:00:05.000Z"
  },
  "items": [
    { "index": 0, "operationId": "a1...", "status": "completed", "errorCode": null, "errorMessage": null, "retryCount": 0 },
    { "index": 1, "operationId": "b2...", "status": "executing", "errorCode": null, "errorMessage": null, "retryCount": 0 }
  ],
  "failures": []
}

batch.status describes dispatch only: accepted, dispatching, dispatched, partially_dispatched or dispatch_failed. Each item's result is in items[].status. An item that failed before dispatch has operationId: null and also appears in failures as { index, idempotencyKey, code, message }.

Retry failed items

Re-runs items whose latest operation ended failed, expired or voided, or that never became an operation. Completed and running items are never resent. Each item can be retried 3 times. No body.

POST/api/chain_relayers/portal/batch/:id/retry

curl -X POST "https://apiv2.tronergy.io/api/chain_relayers/portal/batch/5e1d7c2a-4b3f-4e9a-8d1c-2f6a9b0e3d77/retry" \
  -H "x-api-key: $TRONERGY_API_KEY"

const response = await fetch("https://apiv2.tronergy.io/api/chain_relayers/portal/batch/5e1d7c2a-4b3f-4e9a-8d1c-2f6a9b0e3d77/retry", {
  method: "POST",
  headers: {
    "x-api-key": process.env.TRONERGY_API_KEY,
  },
});

const data = await response.json();

import os
import requests

response = requests.post(
    "https://apiv2.tronergy.io/api/chain_relayers/portal/batch/5e1d7c2a-4b3f-4e9a-8d1c-2f6a9b0e3d77/retry",
    headers={
        "x-api-key": os.environ["TRONERGY_API_KEY"],
    },
)
data = response.json()

Parameters

idstringrequiredpath

Batch ID.

Response (202)

{ "ok": true, "batchId": "5e1d...", "retried": [{ "index": 1 }] }

Retry cannot know whether a failed operation's transaction reached the network. Check the item's txHash first.

Errors: 409 BATCH_NOT_RETRYABLE (still dispatching), 409 NO_RETRYABLE_ITEMS, 409 RETRY_BUDGET_EXHAUSTED (with indices), 429 RATE_LIMITED.

Batches

Submit a batchCopy Anchor Link

Get a batchCopy Anchor Link

Retry failed itemsCopy Anchor Link

On this page

Submit a batch

Get a batch

Retry failed items