The primary way to use the Subscription API or WebSockets is through standard JSON-RPC methods. See the Using JSON-RPC Requests section below to get started.
For a full list of Subscription API endpoints and supported chains see the Subscription API Endpoints doc. Below are the subscription endpoints available and the corresponding docs for each of them.
Note: alchemy_minedTransactions and alchemy_pendingTransactions are only
supported on the following: Ethereum, Arbitrum, Polygon and Optimism.
| Subscription Type | Description |
|---|---|
| alchemy_minedTransactions | Emits full transaction objects or hashes that are mined on the network based on provided filters and block tags. |
| alchemy_pendingTransactions | Emits full transaction objects or hashes that are sent to the network, marked as "pending", based on provided filters. |
| newPendingTransactions | Emits transaction hashes that are sent to the network and marked as "pending". |
| newHeads | Emits new blocks that are added to the blockchain. |
| logs | Emits logs attached to a new block that match certain topic filters. |
| monadNewHeads | Fires a notification each time as soon as a block is Proposed and the node has a chance to speculatively execute. |
| monadLogs | Emits logs attached to a new block that match certain topic filters as soon as the block is Proposed and the node has a chance to speculatively execute. |
WebSockets is a bidirectional communication protocol that maintains a network connection between a server and a client. Unlike HTTP, with WebSockets clients don't need to continuously make requests when they want information.
Instead, an open WebSocket connection can push network updates to clients by allowing them to subscribe to certain network states, such as new transactions or blocks being added to the blockchain.
The eth_subscribe and eth_unsubscribe JSON-RPC methods allow you to access WebSockets.
To begin, open a WebSocket using the WebSocket URL for your app. You can find your app's WebSocket URL by opening the app's page in your dashboard and clicking "View Key".
Note that your app's URL for WebSockets is different from its URL for HTTP requests, but both can be found in the app's "Network" tab.
Next, install a command line tool for making WebSocket requests such as wscat. Using wscat, you can send requests as follows:
$ wscat -c wss://eth-mainnet.ws.g.alchemy.com/v2/demo
// create subscription
> {"id": 1, "method": "eth_subscribe", "params": ["newHeads"]}
< {"jsonrpc":"2.0","id":1,"result":"0xcd0c3e8af590364c09d0fa6a1210faf5"}
// incoming notifications
< {"jsonrpc":"2.0","method":"eth_subscription","params":{"subscription":"0xcd0c3e8af590364c09d0fa6a1210faf5","result":{"difficulty":"0xd9263f42a87",<...>, "uncles":[]}}}
< {"jsonrpc":"2.0","method":"eth_subscription","params":{"subscription":"0xcd0c3e8af590364c09d0fa6a1210faf5","result":{"difficulty":"0xd90b1a7ad02", <...>, "uncles":["0x80aacd1ea4c9da32efd8c2cc9ab38f8f70578fcd46a1a4ed73f82f3e0957f936"]}}}
// cancel subscription
> {"id": 1, "method": "eth_unsubscribe", "params": ["0xcd0c3e8af590364c09d0fa6a1210faf5"]}
< {"jsonrpc":"2.0","id":1,"result":true}Don't Use HTTP Methods Over WebSockets!
Though it's currently possible to send all your HTTP requests over Websockets, we discourage our developers from doing so. Instead, you should only send eth_subscribe and eth_unsubscribe requests to WebSockets.
This is for several reasons:
- You won't receive HTTP status codes in WebSockets responses, which can be useful and actionable.
- Because individual HTTP requests are load-balanced in our infrastructure to the fastest possible server, you'll add additional latency by sending JSON-RPC requests over WebSockets.
- WebSockets client-side handling has many tricky edge cases and silent failure modes, which can make your dApp less stable.
The following limits apply for WebSocket connections:
- There is a limit of 100 WebSocket connections for the FREE tier and 2,000 WebSocket connections for all other tiers.
- There is a limit of 1,000 unique subscriptions per WebSocket connection.
- The maximum size of a JSON-RPC
batchrequest that can be sent over a WebSocket connection is 1000 - The maximum number of concurrent JSON-RPC requests (i.e. requests awaiting responses) on a single WebSocket connection is 200
| Error Code | Error Message | Solution |
|---|---|---|
32600 | "Sorry, the maximum batch request size is 1000. Please reduce the size of your request and try again." | Occurs when user attempts to send high-volume JSON-RPC traffic over Websockets. We recommend this traffic be sent over HTTP instead to optimize server backends. |
1008 | "WebSocket connection limit reached for this app. Please close existing connections and try again." | Triggered when the number of open WebSocket connections for the app reaches the allowed limit. Close unused connections to restore access. |
1008 | "This app has exceeded its limit of open WebSockets. Please close some other connections first." | Triggered when the team previously exceeded the limit and tries to reconnect again before the backoff interval expires. Close existing connections and wait. |
1008 | "You have exceeded the maximum number of concurrent requests on a single WebSocket. At most 200 concurrent requests are allowed per WebSocket." | Triggered when a client has too many pending JSON-RPC requests on a single WebSocket. Ensure each request completes before sending more. |
32603 | "You have exceeded the maximum number of subscriptions on a single WebSocket." | Triggered when a client has too many subscriptions on a single WebSocket. Unsubscribe before creating new subscriptions. |