Subscription API (Websockets)
Learn how to subscribe to pending transactions, log events, new blocks and more using Websockets on Ethereum, Polygon, and Arbitrum.

How to use Websockets

The subscription API endpoints (eth_subscribe and eth_unsubscribe) are only supported over Websockets. Websockets are different from HTTP requests. To learn more about how to use websockets check out the guide belowπŸ‘‡

Use Cases

We recommend using websocket subscriptions anytime you want to continually receive information or data. Check out the guide below for an example use case:

eth_subscribe

Creates a new subscription for desired events. Sends data as soon as it occurs.

A note on limits over 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.

Parameters

Returns

  • Subscription ID: This ID will be attached to all received events and can also be used to cancel the subsciption using eth_unsubscribe.

Subscription Events

While the subscription is active, you will receive events formatted as an object described below:
  • Event Object:
    • jsonrpc: Always "2.0"
    • method: Always "eth_subscription"
    • params: An object with the following fields:
      • subscription: The subscription ID returned by the eth_subscribe call which created this subscription.
      • result: An object whose contents vary depending on the type of subscription.

Subscription types

The following subscription types are accepted in all eth_subscribe websocket requests through your Alchemy endpoint.

alchemy_newFullPendingTransactions

Returns the transaction information for all transactions that are added to the pending state. This subscription type subscribes to pending transactions, similar to the standard Web3 call web3.eth.subscribe("pendingTransactions"), but differs in that it emits full transaction information rather than just transaction hashes.
The alchemy_newFullPendingTransactions subscription type is costly to maintain and thus requires a large number of compute units since it emits full transaction information instead of just transaction hashes. We do not recommend keeping this subscription open for long periods of time for non-enterprise tier users.
NOTE:
  • The naming of this subscription is different from the naming of the web3 subscription API, alchemy_fullPendingTransactions. This is to maintain naming standard with Web3.js.
  • This method is only supported on Ethereum and Polygon networks (Mainnet and Mumbai).

Parameters

  • None

Request

wscat
alchemyweb3.js
1
// initiate websocket stream first
2
wscat -c wss://eth-mainnet.alchemyapi.io/v2/demo
3
​
4
// then call subscription
5
{"jsonrpc":"2.0","id": 2, "method": "eth_subscribe", "params": ["alchemy_newFullPendingTransactions"]}
Copied!
1
// Installation: https://github.com/alchemyplatform/alchemy-web3
2
const { createAlchemyWeb3 } = require("@alch/alchemy-web3");
3
​
4
// Initialize alchemy-web3 object.
5
const web3 = createAlchemyWeb3(`wss://eth-mainnet.alchemyapi.io/v2/demo`);
6
​
7
// Subcribes to the event and prints results
8
web3.eth.subscribe("alchemy_newFullPendingTransactions").on("data", (data) => console.log(data));
Copied!

Result

1
{"id":1,"result":"0x9a52eeddc2b289f985c0e23a7d8427c8","jsonrpc":"2.0"}
2
​
3
{
4
"jsonrpc":"2.0",
5
"method":"eth_subscription",
6
"params":{
7
"result":{
8
"blockHash":null,
9
"blockNumber":null,
10
"from":"0xa36452fc31f6f482ad823cd1cf5515177d57667f",
11
"gas":"0x1adb0",
12
"gasPrice":"0x7735c4d40",
13
"hash":"0x50bff0736c713458c92dd1848d12f3354149be1363123dae35e94e0f2a9d56bf",
14
"input":"0xa9059cbb0000000000000000000000000d0707963952f2fba59dd06f2b425ace40b492fe0000000000000000000000000000000000000000000015b1111266cfca100000",
15
"nonce":"0x0",
16
"to":"0xea38eaa3c86c8f9b751533ba2e562deb9acded40",
17
"transactionIndex":null,
18
"value":"0x0",
19
"v":"0x26",
20
"r":"0x195c2c1ed126088e12d290aa93541677d3e3b1d10f137e11f86b1b9227f01e3b",
21
"s":"0x60fc4edbf1527832a2a36dbc1e63ed6193a6eee654472fbebbf88ef1750b5344"},
22
"subscription":"0x9a52eeddc2b289f985c0e23a7d8427c8"
23
}
24
}
Copied!

alchemy_filteredNewFullPendingTransactions

Returns the transaction information for all transactions that are added to the pending state that match a given filter. Currently supports an address filter, which will return transactions from or to the address.
NOTE: This method is only supported on Ethereum and Polygon networks (Mainnet and Mumbai).

Parameters

  • address: address to receive pending transactions for (sent from or to this address).

Request

wscat
alchemyweb3.js
1
// initiate websocket stream first
2
wscat -c wss://eth-mainnet.alchemyapi.io/v2/demo
3
​
4
// then call subscription
5
{"jsonrpc":"2.0","id": 1, "method": "eth_subscribe", "params": ["alchemy_filteredNewFullPendingTransactions", {"address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"}]}
Copied!
1
// Installation: https://github.com/alchemyplatform/alchemy-web3
2
const { createAlchemyWeb3 } = require("@alch/alchemy-web3");
3
​
4
// Initialize alchemy-web3 object.
5
const web3 = createAlchemyWeb3(`wss://eth-mainnet.alchemyapi.io/v2/demo`);
6
​
7
// Subcribes to the event and prints results
8
web3.eth.subscribe("alchemy_filteredNewFullPendingTransactions", {"address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"}).on("data", (data) => console.log(data));
Copied!

Result

1
{"id":1,"result":"0x9a52eeddc2b289f985c0e23a7d8427c8","jsonrpc":"2.0"}
2
​
3
{
4
"jsonrpc":"2.0",
5
"method":"eth_subscription",
6
"params":{
7
"result":{
8
"blockHash":null,
9
"blockNumber":null,
10
"from":"0xa36452fc31f6f482ad823cd1cf5515177d57667f",
11
"gas":"0x1adb0",
12
"gasPrice":"0x7735c4d40",
13
"hash":"0x50bff0736c713458c92dd1848d12f3354149be1363123dae35e94e0f2a9d56bf",
14
"input":"0xa9059cbb0000000000000000000000000d0707963952f2fba59dd06f2b425ace40b492fe0000000000000000000000000000000000000000000015b1111266cfca100000",
15
"nonce":"0x0",
16
"to":"0x6B3595068778DD592e39A122f4f5a5cF09C90fE2",
17
"transactionIndex":null,
18
"value":"0x0",
19
"v":"0x26",
20
"r":"0x195c2c1ed126088e12d290aa93541677d3e3b1d10f137e11f86b1b9227f01e3b",
21
"s":"0x60fc4edbf1527832a2a36dbc1e63ed6193a6eee654472fbebbf88ef1750b5344"},
22
"subscription":"0x9a52eeddc2b289f985c0e23a7d8427c8"
23
}
24
}
Copied!

newPendingTransactions

Returns the hash for all transactions that are added to the pending state (regardless if you sent them or not).
NOTE: This method is only supported on Ethereum and Polygon networks (Mainnet and Mumbai).

Parameters

  • None
Request
wscat
alchemyweb3.js
1
// initiate websocket stream first
2
wscat -c wss://eth-mainnet.alchemyapi.io/v2/demo
3
​
4
// then call subscription
5
{"jsonrpc":"2.0","id": 2, "method": "eth_subscribe", "params": ["newPendingTransactions"]}
Copied!
1
// Installation: https://github.com/alchemyplatform/alchemy-web3
2
const { createAlchemyWeb3 } = require("@alch/alchemy-web3");
3
​
4
// Initialize alchemy-web3 object.
5
const web3 = createAlchemyWeb3(`wss://eth-mainnet.alchemyapi.io/v2/demo`);
6
​
7
// Subcribes to the event and prints results
8
web3.eth.subscribe("newPendingTransactions").on("data", (data) => console.log(data));
Copied!
Result
1
{"id":1,"result":"0xc3b33aa549fb9a60e95d21862596617c","jsonrpc":"2.0"}
2
​
3
{
4
"jsonrpc":"2.0",
5
"method":"eth_subscription",
6
"params":{
7
"subscription":"0xc3b33aa549fb9a60e95d21862596617c",
8
"result":"0xd6fdc5cc41a9959e922f30cb772a9aef46f4daea279307bc5f7024edc4ccd7fa"
9
}
10
}
Copied!

newHeads

Emits an event any time a new header (block) is added to the chain, including during a chain reorganization.
NOTE: Chain Reorganizations (ReOrgs)
When a chain reorganization occurs, this subscription will emit an event containing all new headers (blocks) for the new chain. This means that you may see multiple headers emitted with the same height, and when this happens the later header should be taken as the correct one after a reorganization.

Parameters

  • None
Request
wscat
alchemyweb3.js
1
// initiate websocket stream first
2
wscat -c wss://eth-mainnet.alchemyapi.io/v2/demo
3
​
4
// then call subscription
5
{"jsonrpc":"2.0","id": 1, "method": "eth_subscribe", "params": ["newHeads"]}
Copied!
1
// Installation: https://github.com/alchemyplatform/alchemy-web3
2
const { createAlchemyWeb3 } = require("@alch/alchemy-web3");
3
​
4
// Initialize alchemy-web3 object.
5
const web3 = createAlchemyWeb3(`wss://eth-mainnet.alchemyapi.io/v2/demo`);
6
​
7
// Subcribes to the event and prints results
8
web3.eth.subscribe("newHeads").on("data", (data) => console.log(data));
Copied!
Result
1
{"jsonrpc":"2.0", "id":1, "result":"0x9ce59a13059e417087c02d3236a0b1cc"}
2
​
3
{
4
"jsonrpc": "2.0",
5
"method": "eth_subscription",
6
"params": {
7
"result": {
8
"difficulty": "0x15d9223a23aa",
9
"extraData": "0xd983010305844765746887676f312e342e328777696e646f7773",
10
"gasLimit": "0x47e7c4",
11
"gasUsed": "0x38658",
12
"logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
13
"miner": "0xf8b483dba2c3b7176a3da549ad41a48bb3121069",
14
"nonce": "0x084149998194cc5f",
15
"number": "0x1348c9",
16
"parentHash": "0x7736fab79e05dc611604d22470dadad26f56fe494421b5b333de816ce1f25701",
17
"receiptRoot": "0x2fab35823ad00c7bb388595cb46652fe7886e00660a01e867824d3dceb1c8d36",
18
"sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
19
"stateRoot": "0xb3346685172db67de536d8765c43c31009d0eb3bd9c501c9be3229203f15f378",
20
"timestamp": "0x56ffeff8",
21
"transactionsRoot": "0x0167ffa60e3ebc0b080cdb95f7c0087dd6c0e61413140e39d94d3468d7c9689f"
22
},
23
"subscription": "0x9ce59a13059e417087c02d3236a0b1cc"
24
}
25
}
Copied!

logs

Emits logs which are part of newly added blocks that match specified filter criteria.
NOTE: Chain Reorganizations (ReOrgs)
When a chain reorganization occurs, logs that are part of blocks on the old chain will be emitted again with the property removed set to true.
Logs which are part of the blocks on the new chain are also emitted, it is possible to see logs for the same transaction multiple times in the case of a reorganization.

Parameters

An object with the following fields:
  • adddress (optional): [string] or [array of strings] Singular address or array of addresses.
    • Only logs created from one of these addresses will be emitted.
  • topics: an array of topic specifiers.
    • Each topic specifier is either null, a single string, or an array of strings.
    • For every non null topic, a log will be emitted when activity associated with that topic occurs.
Topic Specifications:
  • []: Any topics allowed.
  • [A]: A in first position (and anything after).
  • [null, B]: Anything in first position and B in second position (and anything after).
  • [A, B]: A in first position and B in second position (and anything after).
  • [[A, B], [A, B]]: (A or B) in first position and (A or B) in second position (and anything after).
To learn more about how log topics work, check out this page.

Request

wscat
alchemyweb3.js
1
// initiate websocket stream first
2
wscat -c wss://eth-mainnet.alchemyapi.io/v2/demo
3
​
4
// then call subscription
5
{"jsonrpc":"2.0","id": 1, "method": "eth_subscribe", "params": ["logs", {"address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]}]}
Copied!
1
// Installation: https://github.com/alchemyplatform/alchemy-web3
2
const { createAlchemyWeb3 } = require("@alch/alchemy-web3");
3
​
4
// Initialize alchemy-web3 object.
5
const web3 = createAlchemyWeb3(`wss://eth-mainnet.alchemyapi.io/v2/demo`);
6
​
7
// Subcribes to the event and prints results
8
web3.eth.subscribe("logs", {"address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]}).on("data", (data) => console.log(data));
Copied!

Result

1
{
2
"jsonrpc":"2.0",
3
"id":1,
4
"result":"0x4a8a4c0517381924f9838102c5a4dcb7"
5
}
6
​
7
{
8
"jsonrpc":"2.0",
9
"method":"eth_subscription",
10
"params": {
11
"subscription":"0x4a8a4c0517381924f9838102c5a4dcb7",
12
"result":{
13
"address":"0x8320fe7702b96808f7bbc0d4a888ed1468216cfd",
14
"blockHash":"0x61cdb2a09ab99abf791d474f20c2ea89bf8de2923a2d42bb49944c8c993cbf04",
15
"blockNumber":"0x29e87",
16
"data":"0x00000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000003",
17
"logIndex":"0x0",
18
"topics":["0xd78a0cb8bb633d06981248b816e7bd33c2a35a6089241d099fa519e361cab902"],
19
"transactionHash":"0xe044554a0a55067caafd07f8020ab9f2af60bdfe337e395ecd84b4877a3d1ab4",
20
"transactionIndex":"0x0"
21
}
22
}
23
}
Copied!

eth_unsubscribe

Cancels an existing subscription so that no further events are sent.

Parameters

  • Subscription ID - ID for the subscription to cancel, previously returned from an eth_subscribe call.

Returns

true if a subscription was successfully cancelled, or false if no subscription existed with the given ID.
Request
wscat
alchemyweb3.js
1
// initiate websocket stream first
2
wscat -c wss://eth-mainnet.alchemyapi.io/v2/demo
3
​
4
// then call unsubscribe
5
{"jsonrpc":"2.0", "id": 1, "method": "eth_unsubscribe", "params": ["0x9cef478923ff08bf67fde6c64013158d"]}
Copied!
1
// Installation: https://github.com/alchemyplatform/alchemy-web3
2
const { createAlchemyWeb3 } = require("@alch/alchemy-web3");
3
​
4
// Initialize alchemy-web3 object.
5
const web3 = createAlchemyWeb3(`wss://eth-mainnet.alchemyapi.io/v2/demo`);
6
​
7
// Example subscription
8
sub = web3.eth.subscribe("newHeads");
9
​
10
// Unsubscribe
11
sub.unsubscribe((error, success) => {
12
if (success) {
13
console.log("F yea, I freed my resources");
14
}
15
);
16
// unsubscribes the subscription
17
subscription.unsubscribe(
Copied!
Result
1
{
2
"jsonrpc":"2.0",
3
"id":1,
4
"result":true
5
}
Copied!

Error Codes

Error Code
Error Message
Solution
32600
"The maximum batch size that can be sent over a websocket connection is 10. Please decrease the batch size 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.
​