Code Examples

Browse 15 runnable Python examples demonstrating AlgoKit Subscriber features. Each example is self-contained and demonstrates specific functionality.

Quick Start

# Clone the repository
git clone https://github.com/algorandfoundation/algokit-subscriber-py.git
cd algokit-subscriber-py

# Install dependencies
uv sync

# Run an example
cd examples/subscriber
uv run python 01_basic_poll_once.py

Prerequisites

• Python >= 3.10
• uv installed
• AlgoKit CLI installed
• LocalNet running for network examples (algokit localnet start)

Examples (15)

Example	Description
Basic Poll Once	Demonstrates a single poll_once() call with a sender filter. Creates a funded sender account, sends 2 self-payment transactions, then uses AlgorandSubscriber to find and verify the matched transactions.
Continuous Subscriber	Demonstrates continuous polling with start/stop and event handlers. Create a subscriber with frequency_in_seconds and wait_for_block_when_at_tip Register event handlers with subscriber.on() Start continuous polling with subscriber.start() Graceful shutdown with signal handlers
Payment Filters	Demonstrates payment transaction filters: Filter by sender, receiver, amount range, and note prefix Verify each filter matches the expected transactions
Asset Transfer	Demonstrates ASA lifecycle subscription: Subscribe to asset creation with assetCreate filter Subscribe to asset transfers with type and assetId filters Track opt-in and transfer transactions
App Call Subscription	Demonstrates application call subscription with ABI method filtering: Deploy TestingApp from ARC-56 spec Call set_global, emitSwapped, opt_in ABI methods Filter by app_create, method_signature, app_on_complete, app_call_arguments_match Verify each filter matches the expected transactions
Multiple Named Filters	Demonstrates multiple named filters with deduplication: Define multiple filters on a single subscriber Verify transactions are deduplicated across filters Inspect filtersMatched on each transaction
Balance Change Tracking	Demonstrates balance change filtering for ALGO and ASA transfers: Filter by assetId, role, minAbsoluteAmount, and address Inspect balanceChanges array on matched transactions Explore BalanceChangeRole enum values
ARC-28 Event Subscription	Demonstrates ARC-28 event parsing, filtering, and inspection: Define event definitions matching ARC-56 spec Configure config-level arc28_events for event parsing Filter transactions by emitted event names Inspect parsed event data (args, args_by_name)
Inner Transaction Subscription	Demonstrates inner transaction subscription and parent-child relationships: Subscribe to inner payment transactions by sender/receiver Verify parentTransactionId links to the parent app call Inspect inner transaction ID format Verify parent transaction’s inner_txns array
Batch Handling & Data Mappers	Demonstrates mapper transforms with on_batch and on handler patterns: Define a mapper to transform list[SubscribedTransaction] to custom types Compare on_batch (fires once per poll) vs on (fires per transaction) Verify type safety with mapped data
Watermark Persistence	Demonstrates file-backed watermark persistence across multiple polls: Implement get/set callbacks using a temp file Poll twice: batch 1 catches first 2 txns, batch 2 catches next 2 txns Verify watermark advances between polls Verify no duplication across polls Explain at-least-once delivery semantics
Sync Behaviours	Demonstrates all 4 sync behaviours and maxRoundsToSync comparison: sync-oldest: incremental catchup from watermark skip-sync-newest: jump to tip, discard history sync-oldest-start-now: hybrid first-start behavior fail: throw when too far behind
Custom Filters	Demonstrates custom filter predicates with multi-condition logic: Use customFilter for complex matching (amount + note + sender allowlist) Compose customFilter with standard filter fields Inspect full SubscribedTransaction fields available in customFilter
Stateless Subscriptions	Demonstrates getSubscribedTransactions for serverless patterns. Use the stateless function instead of the AlgorandSubscriber class Manage watermark externally between calls Verify no overlap between consecutive calls
Lifecycle Hooks & Error Handling	Demonstrates lifecycle hooks and retry patterns. Hook execution order: on_before_poll -> processing -> on_poll -> inspect start(inspect) callback in continuous polling Error recovery with on_error and retry logic