Subscription API Quickstart
Learn how to subscribe to pending transactions, log events, new blocks and more using WebSockets on Ethereum, Polygon, Arbitrum, and Optimism.
Getting Started
There are two primary ways to use the Subscription API or WebSockets:
- Using the Alchemy SDK (recommended)
- Using standard JSON-RPC methods
Subscription API Endpoints
For a full list of Subscription API endpoints and supported chains see the Subscription API Endpoints doc, or if you’re using the Alchemy SDK see SDK WebSockets Endpoints. 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.
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, or to make requests from your project files instead of the command line, check out the Alchemy SDK. Using wscat
, you can send requests as follows:
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:
WebSocket Limits
The following limits apply for WebSocket connections:
- There is a limit of 20,000 WebSocket connections per API Key as well as 1,000 parallel WebSocket subscriptions per WebSocket connection, creating a maximum of 20 million subscriptions per application.
- The maximum size of a JSON-RPC
batch
request that can be sent over a WebSocket connection is 20 - Free tier users will be limited to 10 concurrent requests per WebSocket connection.