Batch requests are a single HTTP request that contains multiple API calls nested within it. You can send several request objects together at the same time in an array, and you'll 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 -- you should match request objects to response objects based on the id member of each object.
In several use cases that contain different JSON-RPC endpoints, the batching approach can get complicated.
For these reasons, Alchemy does not recommend using batch requests as they can be less reliable compared to individual API calls.
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.
The maximum size of a JSON-RPC batch request that you can send over a WebSocket connection is 20.
Batch requests are currently not supported on some of the Alchemy's Enhanced APIs and Trace/Debug APIs, this includes the APIs listed below:
- Transfers API
- Transact APIs
- Transaction Receipts API
- Token APIs
- Subscription APIs (except
newPendingTransactionsnewHeadsandlogs) - Trace APIs
- Debug APIs
Batch requests are formatted the same as individual API requests, but the body of the request is an array containing the individual API calls you want to make rather than a single API call. See 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}'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": []}]'Batch Requests are usually for JSON-RPC endpoints, but Alchemy provides 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"}]'Batch requests always return a 200 HTTP status code, even if some or all requests within the batch fail. Parse the JSON-RPC error codes in the response to determine if the individual requests within the batch succeeded or failed.