Scanning for events

What you'll learn

In this quickstart, you'll create a Chainhook predicate to track STX transfers on the Stacks blockchain and scan historical data to see it in action.

How to create a Chainhook predicate for tracking STX transfers

How to scan historical blockchain data using Chainhook

Prerequisites

To follow this guide, you'll need:

For installation instructions, visit the Chainhook installation guide.

Quickstart

Generate a predicate file

Chainhook uses predicates to define what blockchain events to track. Generate a template predicate file:

Terminal

$ chainhook predicates new stx-transfer.json --stacks
[32mCreated predicate template[0m [1mstx-transfer.json[0m

This creates a boilerplate JSON file with the basic predicate structure. The --stacks flag specifies you're tracking Stacks events (use --bitcoin for Bitcoin).

Configure event tracking

Open stx-transfer.json and update the if_this section to track STX transfer events:

stx-transfer.json

{
  "chain": "stacks",
  "uuid": "87ac9bff-1052-4d02-9c79-3768a6f08a09",
  "name": "STX Transfer",
  "version": 1,
  "networks": {
    "mainnet": {
      "start_block": 154670,
      "if_this": {
        "scope": "stx_event",
        "actions": ["transfer"]
      },
      "then_that": {
        "file_append": {
          "path": "stx-transfers.txt"
        }
      }
    }
  }
}

This predicate will:

Track all STX transfer events (scope: "stx_event", actions: ["transfer"])
Start scanning from block 154670
Append matching events to stx-transfers.txt

Scan for events

Run the scan command to search historical blockchain data:

Terminal

$ chainhook predicates scan stx-transfer.json --mainnet
[33mDownloading Stacks chainstate archive...[0m
[32mScanning blocks 154670 to 155000[0m
[32mFound 1,234 matching events[0m
[32mResults written to stx-transfers.txt[0m

First-time setup

The first scan downloads a chainstate archive from Hiro Archive. Subsequent scans use the cached data for faster performance.

View results

Check the output file to see the transfer events:

Terminal

$ head -5 stx-transfers.txt
{"apply":[{"block_identifier":{"hash":"0x123...","index":154670},"transactions":[{"transaction_identifier":{"hash":"0xabc..."},"operations":[{"operation_identifier":{"index":0},"type":"stx_transfer","status":"success","account":{"address":"SP123..."},"amount":{"value":"1000000","currency":{"symbol":"STX","decimals":6}}}]}]}]}

Each line contains a JSON payload with transfer details including sender, recipient, amount, and block information.

Next steps

Design custom predicates

Learn to create predicates for contract calls, NFT transfers, and more

Run Chainhook as a service

Set up continuous blockchain monitoring with webhook delivery

Explore Stacks predicates

See all available event types and filtering options