Batch Requests

Batch requests allow multiple API calls to be combined into a single HTTP request, reducing network overhead and improving efficiency. Below are details on how batch requests work, their restrictions, and examples.

What is a batch request?

A batch request bundles multiple API calls into one HTTP request. It's a standard feature in the JSON-RPC 2.0 specification. Each individual call within the batch is processed independently, and responses may return in any order, so it's recommended to make use of the id field to identify each sub-request. Here's an example of a batch request (POST body):

[
    {
        "jsonrpc": "2.0",
        "id": 1,
        "method": "eth_blockNumber",
        "params": []
    },
    {
        "jsonrpc": "2.0",
        "id": 2,
        "method": "eth_blockNumber",
        "params": []
    }
]

And the corresponding response can look like this:

[
    {
        "result": "0x3333ccd",
        "id": 1,
        "jsonrpc": "2.0"
    },
    {
        "result": "0x3333ccd",
        "id": 2,
        "jsonrpc": "2.0"
    }
]

Having the convenience in some cases though, it's important to note that

1. The CUs used by a batch request are no different than if they were sent separately as individual requests.
2. The HTTP status code of the response will be 200 even if a batch contains failed sub-requests, so it's important to parse the response body to determine if any of the sub-requests failed.
3. There is an upper limit of the number of sub-requests in a batch and some specific ecosystem and method restrictions which will be described in sections below.

Due to the increased complexity and restrictions as mentioned above, it's generally not recommended to use batch requests unless necessary.

What APIs support batch requests?

1. Core HTTP APIs: ✅️ (like the example above)
2. Core WebSocket APIs: ❌
3. Advanced APIs: ❌

Restrictions and exceptions

Batch requests in Core HTTP APIs are subject to the following limitations:

1. General upper limit: The maximum allowed batch size is 500. Solana has a stricter limit of 100.
2. EVM method restrictions: Debug APIs are not recommended to be in a batch more than once.
3. Solana method restrictions: It's not recommended for resource-intensive methods to be in a batch more than once (such as getProgramAccounts, getTokenAccountsByOwner, getTokenLargestAccounts, getTokenAccountsByDelegate and so on). A current hard limit is 5 and this might change without further notice.

Best practices

• Use unique id values for each sub-request to map responses correctly.
• Control the batch size to be under the upper limits.
• Avoid including unsupported or restricted methods in the batch to prevent errors.
• Monitor updates to API documentation for changes in limits or methods.