Learn how to scan the Stacks blockchain for STX transactions.

In this quickstart guide, you will set up Chainhook to generate and scan predicates on the Stacks blockchain. You will learn how to generate predicates and run basic commands using the CLI to scan and inspect blockchain events.

Check out the run Chainhook as a service for a more advanced use case.


Before starting, ensure you have Chainhook installed. If you haven't already, check out the installation guide.

Generate a predicate file

To generate a predicate file, use the predicates new command. This command generates a template that you can use to help set up your own predicate.

chainhook predicates new stx-transfer.json --stacks 

The --stacks flag is required and allows you to specify the network to scan. Other options include --bitcoin.

Track the latest stx_event for a given address

The generated file contains helpful boilerplate configuration, but you still need to make some edits to tell it to track specific Stacks-related transactions.

To do this, update your if_this construct in your stx-transfer.json file.

  "if_this": {
    "scope": "stx_event",
    "actions": ["transfer"]

Other available actions include mint, burn, and lock. For more information on these actions, check out the predicates section.

Scanning for events

With your updated predicate file, you can now use the predicate scan command to scan for stx_event transactions.

chainhook predicates scan /path/to/stx-transfer.json --mainnet

When running scan for the first time, a chainstate archive will be downloaded. The subsequent scans will use the cached chainstate if already present, speeding up iterations and the overall feedback loop. For more information on the Hiro Archive, click here.

Next steps