API Reference
Alchemy Login

Address Activity Webhook

Get real-time updates of value and token transfers for the addresses that you track using the Address Activity webhook

📘

Which chains are supported?

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



Introduction

Alchemy's Address Activity webhook tracks all ETH, ERC20, ERC721 and ERC1155 transfers. This provides your app with real-time state changes when an address sends/receives tokens or ETH. A maximum of 100,000 addresses can be tracked by a single webhook.

📘

TIP

If you are looking for historical activity, check out the Transfers API Endpoints.

Types of transfers

There are three main types of transfers that are captured when receiving a fromAddress activity response.

Transfer typeDescription
External ETHTop-level transactions from an EOA (Externally Owned Account).
TokenEvent logs for ERC20, ERC721, and ERC1155 transfers.
Internal ETHInternal Transfers from a smart contract address.

🚧

Note on Internal Transfers

  1. Internal transfers are currently only supported on Ethereum, Polygon, Arbitrum, Optimism and Base. Support for other networks is a WIP!
  2. Internal Transfers with the call type delegatecall are not supported on Alchemy. Although they have a value associated with them, they don't transfer a value. For details read the Ethereum Yellow Paper. Internal transfer miner rewards are also unsupported on Alchemy.

Example Response

Whenever one of the addresses that you are tracking sends/receives tokens or ETH, you receive a response from the webhook that looks like this:

{
  "webhookId": "wh_k63lg72rxda78gce",
  "id": "whevt_vq499kv7elmlbp2v",
  "createdAt": "2024-01-23T07:42:26.411977228Z",
  "type": "ADDRESS_ACTIVITY",
  "event": {
    "network": "ETH_MAINNET",
    "activity": [
      {
        "blockNum": "0xdf34a3",
        "hash": "0x7a4a39da2a3fa1fc2ef88fd1eaea070286ed2aba21e0419dcfb6d5c5d9f02a72",
        "fromAddress": "0x503828976d22510aad0201ac7ec88293211d23da",
        "toAddress": "0xbe3f4b43db5eb49d1f48f53443b9abce45da3b79",
        "value": 293.092129,
        "erc721TokenId": null,
        "erc1155Metadata": null,
        "asset": "USDC",
        "category": "token",
        "rawContract": {
          "rawValue": "0x0000000000000000000000000000000000000000000000000000000011783b21",
          "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
          "decimals": 6
        },
        "typeTraceAddress": null,
        "log": {
          "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
          "topics": [
            "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
            "0x000000000000000000000000503828976d22510aad0201ac7ec88293211d23da",
            "0x000000000000000000000000be3f4b43db5eb49d1f48f53443b9abce45da3b79"
          ],
          "data": "0x0000000000000000000000000000000000000000000000000000000011783b21",
          "blockNumber": "0xdf34a3",
          "transactionHash": "0x7a4a39da2a3fa1fc2ef88fd1eaea070286ed2aba21e0419dcfb6d5c5d9f02a72",
          "transactionIndex": "0x46",
          "blockHash": "0xa99ec54413bd3db3f9bdb0c1ad3ab1400ee0ecefb47803e17f9d33bc4d0a1e91",
          "logIndex": "0x6e",
          "removed": false
        }
      },
      {
        "blockNum": "0xdf34a3",
        "hash": "0xc84eeeb72d2b23161fd93b088f304902cbd8b4510f1455a65fdac160e37b3173",
        "fromAddress": "0x71660c4005ba85c37ccec55d0c4493e66fe775d3",
        "toAddress": "0x7853b3736edba9d7ce681f2a90264307694f97f2",
        "value": 2400,
        "erc721TokenId": null,
        "erc1155Metadata": null,
        "asset": "USDC",
        "category": "token",
        "rawContract": {
          "rawValue": "0x000000000000000000000000000000000000000000000000000000008f0d1800",
          "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
          "decimals": 6
        },
        "typeTraceAddress": null,
        "log": {
          "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
          "topics": [
            "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
            "0x00000000000000000000000071660c4005ba85c37ccec55d0c4493e66fe775d3",
            "0x0000000000000000000000007853b3736edba9d7ce681f2a90264307694f97f2"
          ],
          "data": "0x000000000000000000000000000000000000000000000000000000008f0d1800",
          "blockNumber": "0xdf34a3",
          "transactionHash": "0xc84eeeb72d2b23161fd93b088f304902cbd8b4510f1455a65fdac160e37b3173",
          "transactionIndex": "0x48",
          "blockHash": "0xa99ec54413bd3db3f9bdb0c1ad3ab1400ee0ecefb47803e17f9d33bc4d0a1e91",
          "logIndex": "0x74",
          "removed": false
        }
      }
    ]
  }
}

Field Definitions

Below you can find descriptions for each field of the response.

FieldDescriptionValue
webhookIdUnique ID of the webhook destination.wh_octjglnywaupz6th
idID of the event.whevt_ogrc5v64myey69ux
createdAtTimestamp when the webhook was created.2022-02-28T17:48:53.306Z
typeWebhook event type.ADDRESS_ACTIVITY
eventMined transaction object.N/A
networkThe default network for the webhook.MATIC_MAINNET
activityList of transfer events whose from or to address matches the address configured in the webhook.N/A
categoryThe external, internal, erc721, erc1155, erc20, or token category label for the transfer.

NOTE: tokenmaps to a transfer of an ERC20 OR ERC721 token		token
fromAddressTransfer from address.0x59479de9d374bdbcba6c791e5d036591976fe422
toAddressTransfer to address.0x59479de9d374bdbcba6c791e5d036591976fe425
erc721TokenIdRaw erc721 token ID.0x1
rawContractUnderlying contract data.N/A
rawValueThe raw transfer value.0x
addressContract address.0x93C46aA4DdfD0413d95D0eF3c478982997cE9861
logReturned log of the token transfer event.N/A
removedTransaction is in a chain re-org & no longer in the canonical chain.false
addressLog origination address.0x93C46aA4DdfD0413d95D0eF3c478982997cE9861
dataNon-indexed arguments of the log.0x
topicsArray of zero to four 32 bytes of indexed log arguments.0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef
blockNumthe block where the transfer occurred (hex string)N/A
hashtransaction hash (hex string)N/A
value converted asset transfer value as a number (raw value divided by contract decimal). Omitted if erc721 transfer or contract decimal is not availableN/A
assetETH or the token's symbol. Omitted if not defined in the contract and not available from other sourcesN/A
erc1155MetadataA list of objects containing the ERC1155 tokenId (hex string) and value (hex string). Omitted if not an ERC1155 transferN/A
decimalcontract decimal (hex string). Omitted if not defined in the contract and not available from other sources.N/A
typeTraceAddressthe type of internal transfer (call, staticcall, create, suicide) followed by the trace address (ex. call_0_1). Omitted if not internal transfer. (note you can use this as a unique id for internal transfers since they will have the same parent hash)N/A

How to Set-Up Address Activity Webhook

  1. In your Alchemy Dashboard click the Notify tab.
  2. Find Address Activity and click the CREATE WEBHOOK button on the right side of the window.

  1. Select your CHAIN in the dropdown. Then choose your NETWORK.
  2. Paste your unique webhook URL into the WEBHOOK URL field.
  3. Enter your ETHEREUM ADDRESSES.

  1. Test your webhook by clicking the TEST WEBHOOK button.
  2. After the test is successful, click CREATE WEBHOOK. Your webhook appears in the list.
  3. Check your endpoint to see the responses.

Useful Endpoints

EndpointDescription
Webhook AddressesGet all addresses for an Address Activity webhook
Update Webhook AddressesAdd or remove addresses from a specific webhook.
Create WebhookThis endpoint allows you to create a webhook programatically.
Delete WebhookAllows you to delete a webhook.
Update WebhookAllows you to set status of webhooks to active or inactive.
ReadMe