The logs subscription type emits logs that match a specified topic filter and are included in newly added blocks. To learn more about logs on Ethereum and other EVM chains, check out Understanding Logs: Deep Dive into eth_getLogs.

📘

Note on 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 that are part of the blocks on the new chain are also emitted so it is possible to see logs for the same transaction multiple times in the case of a reorganization.

If removed is not included in the response payload then the logs are still a part of the canonical chain.

Supported Networks

📘

Which chains are supported?

Check the Services page for details about product and chain support!

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 (up to 4 topics allowed per address).
  • 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 tutorial.

Request

// initiate websocket stream first
wscat -c wss://eth-mainnet.g.alchemy.com/v2/demo

// then call subscription 
{"jsonrpc":"2.0","id": 1, "method": "eth_subscribe", "params": ["logs", {"address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]}]}

import { Alchemy, Network } from "alchemy-sdk";
import { ethers } from "ethers";

const settings = {
  apiKey: "demo", // Replace with your Alchemy API Key.
  network: Network.ETH_MAINNET, // Replace with your network.
};
const alchemy = new Alchemy(settings);

// This filter could also be generated with the Contract or
// Interface API. If address is not specified, any address
// matches and if topics is not specified, any log matches
const filter = {
  address: "dai.tokens.ethers.eth",
  topics: [ethers.utils.id("Transfer(address,address,uint256)")],
};

alchemy.ws.on(filter, (log, event) => {
  // Emitted whenever a DAI token transfer occurs
});

// Notice this is an array of topic-sets and is identical to
// using a filter with no address (i.e. match any address)
const topicSets = [
  ethers.utils.id("Transfer(address,address,uint256)"),
  null,
  [address1, address2],
];

alchemy.ws.on(topicSets, (log, event) => {
  // Emitted any token is sent TO either address
});

Result

{
    "jsonrpc":"2.0",
    "method":"eth_subscription",
    "params": {
        "subscription":"0x4a8a4c0517381924f9838102c5a4dcb7",
        "result":{
            "address":"0x8320fe7702b96808f7bbc0d4a888ed1468216cfd",
            "blockHash":"0x61cdb2a09ab99abf791d474f20c2ea89bf8de2923a2d42bb49944c8c993cbf04",
            "blockNumber":"0x29e87",
            "data":"0x00000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000003",
            "logIndex":"0x0",
            "topics":["0xd78a0cb8bb633d06981248b816e7bd33c2a35a6089241d099fa519e361cab902"],
            "transactionHash":"0xe044554a0a55067caafd07f8020ab9f2af60bdfe337e395ecd84b4877a3d1ab4",
            "transactionIndex":"0x0"
        }
    }
}

Below you can find the explanation for individual properties of the response:

• jsonrpc: The jsonrpc property specifies the version of the JSON-RPC protocol that is being used, which in this case is "2.0".
• method: The method property specifies the method that was called, which in this case is eth_subscription.
• params: The params property contains the parameters of the method call. In this case, it contains a subscription property, which specifies the subscription identifier, and a result property, which contains the result of the subscription.
• result: The result property contains information about a specific transaction on the Ethereum blockchain.
• address: The address property specifies the address from which this log originated.
• blockhash: The blockHash property specifies the hash of the block in which the transaction was included.
• blockNumber: The blockNumber property specifies the number of the block in which the transaction was included. It is encoded as a hexadecimal string.
• data: Contains one or more 32 Bytes non-indexed arguments of the log.
• logIndex: The logIndex property specifies the index or position of the log entry within the block. It is encoded as a hexadecimal string.
• topics: An array of 0 to 4 32 bytes topic hashes of indexed log arguments (up to 4 topics allowed per address).
• transactionHash: The transactionHash property specifies the hash of the transaction.
• transactionIndex: The transactionIndex property specifies the index or position of the transaction within the block. It is encoded as a hexadecimal string.