Getting Started

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.

Subscription API Endpoints

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.

What are WebSockets and how do they differ from HTTP?

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.

Using JSON-RPC Requests to Access WebSockets

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:

Shell

$ $ 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.

WebSocket Limits

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, with a maximum of 50,000 connections per instance.
No limits on the number of parallel WebSocket subscriptions per WebSocket connection.
The maximum size of a JSON-RPC batch request that can be sent over a WebSocket connection is 1000

Error Codes

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.