⛓️ Batch Calls

Batch calling lets you send multiple JSON-RPC requests in a single API call. Instead of making dozens of separate calls, you can group them together. This reduces the number of network round trips and helps streamline interactions with the blockchain.

All batch requests are processed as raw node requests.

Limits and Recommendations

A batch of up to 50 requests generally works well. However, some methods are more resource-intensive than others. In these cases, even smaller batches can overload nodes and lead to timeouts.

When performance issues occur:

• Reduce the batch size - split large arrays into smaller requests.
• Fallback to single requests if a method is especially heavy.

Hard Limits (per chain)

• Most chains : up to 400 calls per batch
• Polygon: up to 100 calls per batch
• NEAR: not natively supported; Tatum provides an additional 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 is a JSON array of standard JSON-RPC request objects. Each object follows the normal JSON-RPC request schema.

Request Example:

curl --location 'https://api.tatum.io/v3/blockchain/node/{chain-name}/' \
--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 handle batch calls poorly. Large payloads may cause timeouts or degraded performance. Example Optimism.

Best Practices

• ✅ Keep batches under 50 items for reliability.
• ✅ Always use a unique ID per request.
• ✅ Validate each request format and parameters before sending.
• ✅ Distribute heavy workloads across multiple smaller batches.
• ✅ Monitor for timeouts and retry with reduced batch size if needed.