Code Examples

Browse 15 runnable TypeScript examples demonstrating the AlgoKit Subscriber library. Each example is self-contained and demonstrates specific functionality.

Quick Start

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

# Install dependencies
npm install

# Run any example
cd examples/subscriber
npx tsx 01-basic-poll-once.ts

Prerequisites

• Node.js >= 20
• npm
• AlgoKit CLI installed
• LocalNet running for network examples (algokit localnet start)

Examples (15)

Example	Description
Basic Poll Once	This example demonstrates single-poll subscription with a sender filter. Create an AlgorandSubscriber with an in-memory watermark Poll once and inspect the result Verify matched transactions
Continuous Subscriber	This example demonstrates continuous polling with start/stop and event handlers. Create a subscriber with frequencyInSeconds and waitForBlockWhenAtTip Register event handlers with subscriber.on() Start continuous polling with subscriber.start() Graceful shutdown with signal handlers
Payment Filters	This example demonstrates payment transaction filters. Filter by sender, receiver, amount range, and note prefix Verify each filter matches the expected transactions
Asset Transfer Subscription	This example 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	This example demonstrates application call subscription. Subscribe to app creation with appCreate filter Filter by methodSignature for specific ABI methods Filter by appOnComplete for opt-in calls Use appCallArgumentsMatch for custom argument inspection
Multiple Named Filters	This example 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	This example 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	This example demonstrates ARC-28 event parsing, filtering, and inspection. Define event definitions matching ARC-56 spec Configure config-level arc28Events for event parsing Filter transactions by emitted event names Inspect parsed event data (args, argsByName)
Inner Transaction Subscription	This example 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
Batch Handling & Data Mappers	This example demonstrates mapper transforms with onBatch and on handler patterns. Define a mapper to transform SubscribedTransaction[] to custom types Compare onBatch (fires once per poll) vs on (fires per transaction) Verify type safety with mapped data
Watermark Persistence	This example demonstrates file-backed watermark persistence across polls. Implement get/set callbacks for file-based watermark storage Verify watermark advances after each poll Demonstrate at-least-once delivery semantics
Sync Behaviours	This example 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	This example 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	This example 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	This example demonstrates lifecycle hooks and retry patterns. Hook execution order: onBeforePoll -> processing -> onPoll -> inspect start(inspect) callback in continuous polling Error recovery with onError and retry logic