Batch Calls

Batch calling allows you to send multiple JSON-RPC requests within a single API call. Instead of making dozens of individual requests, you can bundle them together into one batch, reducing network round trips and improving overall efficiency when interacting with the blockchain.

All batch requests are forwarded and processed as raw node requests, without additional Gateway-level enhancements or optimisations.

Batch Limits & Recommendations

A batch size of up to 50 requests generally performs well. However, some RPC methods are significantly more resource-intensive than others. In such cases, even smaller batches may overload nodes and result in slow responses or timeouts.

When performance issues occur:

• Reduce batch size – split large batches into smaller groups.
• Fallback to single requests – for especially heavy or computationally expensive methods.

Hard Limits (per chain)

The following hard limits apply to batch requests:

• Most chains: Up to 400 calls per batch
• Polygon: Up to 100 calls per batch
• NEAR: Not natively supported. Tatum provides an additional batching layer with a limit of 5 calls per batch.

📘

Note

Each JSON object in the array counts as an individual request. For example, 10 objects in a batch = 10 requests billed. More details in the following article

Batch Call Format

A batch call consists of a JSON array containing standard JSON-RPC request objects. Each object follows the same schema as a regular single JSON-RPC request.

Request Example:

curl --location 'https://{chain-name}.gateway.tatum.io' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {YOUR_API_KEY}' \
--data '[
  {
    "jsonrpc": "2.0",
    "method": "METHOD_NAME_1",
    "params": [PARAMS_1],
    "id": 1
  },
  {
    "jsonrpc": "2.0",
    "method": "METHOD_NAME_2",
    "params": [PARAMS_2],
    "id": 2
  }
  // Additional requests can be added here
]'

const { TatumSDK, Network } = require('@tatumio/tatum');

(async () => {
const tatum = await TatumSDK.init({
    network: Network.ETHEREUM, 
    apiKey: { v4: 'YOUR-API-KEY'}
    }
)

request = [{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "eth_blockNumber"
    },
    {
      "jsonrpc": "2.0",
      "id": 2,
      "method": "eth_getBlockByNumber",
      "params": [
        "latest",
        true
        ]
    }]
  
const batchRequest = await tatum.rpc.rawBatchRpcCall(request);
console.log(batchRequest)

})();

Performance Considerations

Some blockchains do not handle large batch requests efficiently. Large payloads may result in degraded performance or request timeouts. For example, see known issues with Optimism: Optimism debug_trace and node performance issues.

Best Practices

• ✅ Keep batches under 50 items for reliability.
• ✅ Use a unique ID for each request in the batch.
• ✅ Validate each request format and parameters before sending.
• ✅ Distribute heavy workloads across multiple smaller batches.
• ✅ Monitor for timeouts and retry with reduced batch sizes when necessary.