API Reference
Alchemy Login

Batch Requests

Best practices for making batch json-rpc requests on Ethereum, Polygon, Optimism, and Arbitrum.

What is a batch request?

Batch requests are a single HTTP request that contain multiple API calls nested within it.
Clients can send several request objects together at the same time, filled within an array, will get a corresponding array of response objects from the server.

The server processes all requests of this batch RPC call concurrently, in any order. The response objects returned from a batch RPC can be in any order, the client should match contexts of request objects to response objects based on id member of each object.

Also, In several use-cases which contains different JSON-RPC endpoints, the batching approach can get easily complicated.

Due to these above-mentioned reasons, Alchemy does not recommend using batch requests as they can be less reliable compared to individual API calls.

What is the batch requests limit over HTTP?

The batch request limit over HTTP for all methods and chains is 1000 requests per batch, above this limit requests are likely to be less reliable.

What is the batch requests limit over WebSockets?

The maximum size of a JSON-RPC batch request that can be sent over a WebSocket connection is 20.

Unsupported batch request APIs

Batch requests are currently not supported on some of the Alchemy's Enhanced APIs and Trace/Debug APIs, this includes the APIs listed below:

How do you make a batch request?

Batch requests are formatted the same as individual API requests however, the body of the request is an array containing the individual API calls you wish to make, rather than the single API call. Check out the example with eth_blockNumber below:

Single eth_blockNumber request

curl https://eth-mainnet.g.alchemy.com/v2/your-api-key \
-X POST \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":0}'

import fetch from 'node-fetch'
async function main() {

    const req = {
            method: 'eth_getBlockByNumber',
            params: [],
            id: 0,
            jsonrpc: '2.0',
        }

    const res = await fetch('https://eth-mainnet.g.alchemy.com/v2/your-api-key \', {method: 'POST', body: JSON.stringify(req), headers: {'Content-Type': 'application/json'}})
    const data = await res.json()
}
main().then().catch((err) => console.log(err))

Batch eth_blockNumber request

curl https://eth-mainnet.g.alchemy.com/v2/your-api-key \
-X POST \
-H "Content-Type: application/json" \
-d '[{"jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber", "params": []},
{"jsonrpc": "2.0", "id": 2, "method": "eth_blockNumber", "params": []},
{"jsonrpc": "2.0", "id": 3, "method": "eth_blockNumber", "params": []},
{"jsonrpc": "2.0", "id": 4, "method": "eth_blockNumber", "params": []}]'

import fetch from 'node-fetch'
async function main() {
    const reqs = []
    for (let i = parseInt(process.argv[2]); i < parseInt(process.argv[3]); i++) {
        reqs.push({
            method: 'eth_getBlockByNumber',
            params: [`0x${i.toString(16)}`, false],
            id: i-parseInt(process.argv[2]),
            jsonrpc: '2.0',
        })
    }

    const res = await fetch('https://eth-mainnet.g.alchemy.com/v2/your-api-key \', {method: 'POST', body: JSON.stringify(reqs), headers: {'Content-Type': 'application/json'}})
    const data = await res.json()
}

main().then().catch((err) => console.log(err))

How do you make batch requests over REST?

Batch Requests are usually for JSON-RPC endpoints, but Alchemy SDK is providing support for batch requests over REST as well. It currently only supports one type of REST API for batch requests: getNFTMetadataBatch. Check example code below.

curl --request POST \
     --url https://eth-mainnet.g.alchemy.com/nft/v2/demo/getNFTMetadataBatch \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     --data '[{"0x5180db8F5c931aaE63c74266b211F580155ecac8","1590"},
     					{"0x5280db8F5c931aaE63c74266b211F580155ecac8","1591"}]'

// Github: https://github.com/alchemyplatform/alchemy-sdk-js
// Setup: npm install alchemy-sdk
import { Network, Alchemy } from "alchemy-sdk";

// Optional Config object, but defaults to demo api-key and eth-mainnet.
const settings = {
  apiKey: "demo", // Replace with your Alchemy API Key.
  network: Network.ETH_MAINNET, // Replace with your network.
};

const alchemy = new Alchemy(settings);

// Print NFT metadata returned in the response:
alchemy.nft.getNftMetadata([
  {"0x5180db8F5c931aaE63c74266b211F580155ecac8","1590"},
  {"0x5280db8F5c931aaE63c74266b211F580155ecac8","1591"}
]).then(console.log);

Handling errors in batch requests

Batch requests always return a 200 HTTP status code, even if some or all requests within the batch fail. Therefore, it is important to parse the JSON-RPC error codes in the response to determine if the individual requests within the batch succeeded or failed.

ReadMe