{"id":45689824,"url":"https://github.com/algorandfoundation/algokit-subscriber-py","last_synced_at":"2026-04-08T23:00:56.280Z","repository":{"id":254507905,"uuid":"825411968","full_name":"algorandfoundation/algokit-subscriber-py","owner":"algorandfoundation","description":"Subcriber-py allows you to create Python services that follow or subscribe to the Algorand Blockchain events","archived":false,"fork":false,"pushed_at":"2026-04-08T21:00:43.000Z","size":1547,"stargazers_count":4,"open_issues_count":5,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-04-08T22:13:01.875Z","etag":null,"topics":["algokit","lib"],"latest_commit_sha":null,"homepage":"https://algorandfoundation.github.io/algokit-subscriber-py/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/algorandfoundation.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-07-07T17:38:15.000Z","updated_at":"2026-04-08T21:00:48.000Z","dependencies_parsed_at":"2026-02-04T14:02:41.785Z","dependency_job_id":null,"html_url":"https://github.com/algorandfoundation/algokit-subscriber-py","commit_stats":null,"previous_names":["joe-p/algokit-subscriber-py"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/algorandfoundation/algokit-subscriber-py","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/algorandfoundation%2Falgokit-subscriber-py","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/algorandfoundation%2Falgokit-subscriber-py/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/algorandfoundation%2Falgokit-subscriber-py/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/algorandfoundation%2Falgokit-subscriber-py/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/algorandfoundation","download_url":"https://codeload.github.com/algorandfoundation/algokit-subscriber-py/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/algorandfoundation%2Falgokit-subscriber-py/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31577447,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["algokit","lib"],"created_at":"2026-02-24T16:01:16.286Z","updated_at":"2026-04-08T23:00:56.273Z","avatar_url":"https://github.com/algorandfoundation.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\u003ca href=\"https://github.com/algorandfoundation/algokit-subscriber-py\"\u003e\u003cimg src=\"https://bafybeidbb3a7cgn3unoz4oouk2jme4eavqgqtnskfr4bqhbjku3s52de4a.ipfs.w3s.link/algokit-subscriber-logo.png\" width=60%\u003e\u003c/a\u003e\n\u003c/div\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca target=\"_blank\" href=\"https://algorandfoundation.github.io/algokit-subscriber-py/\"\u003e\u003cimg src=\"https://img.shields.io/badge/docs-repository-74dfdc?logo=github\u0026style=flat.svg\" /\u003e\u003c/a\u003e\n    \u003ca target=\"_blank\" href=\"https://algorand.co/algokit\"\u003e\u003cimg src=\"https://img.shields.io/badge/learn-AlgoKit-74dfdc?logo=algorand\u0026mac=flat.svg\" /\u003e\u003c/a\u003e\n    \u003ca target=\"_blank\" href=\"https://github.com/algorandfoundation/algokit-subscriber-py\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/algorandfoundation/algokit-subscriber-py?color=74dfdc\u0026logo=star\u0026style=flat\" /\u003e\u003c/a\u003e\n    \u003ca target=\"_blank\" href=\"https://algorand.co/algokit\"\u003e\u003cimg  src=\"https://api.visitorbadge.io/api/visitors?path=https%3A%2F%2Fgithub.com%2Falgorandfoundation%2Falgokit-subscriber-py\u0026countColor=%2374dfdc\u0026style=flat\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\nThis library is a simple, but flexible / configurable Algorand transaction subscription / indexing mechanism. It allows you to quickly create Python services that follow or subscribe to the Algorand Blockchain.\n\n\u003e pip install algokit_subscriber\n\n[Documentation](./docs/index.md)\n\n## Quick start\n\n```python\nimport algokit_subscriber as sub\nfrom algokit_utils import AlgorandClient\n\nlocalnet = AlgorandClient.default_localnet()\n\n# Create subscriber\nsubscriber = sub.AlgorandSubscriber(\n    config=sub.AlgorandSubscriberConfig(\n        filters=[\n            sub.SubscriberConfigFilter(\n                name=\"filter1\",\n                type=\"pay\",\n                sender=\"ABC...\",\n            ),\n        ],\n        watermark_persistence=sub.in_memory_watermark(),\n        sync_behaviour=\"skip-sync-newest\",\n    ),\n    algod_client=localnet.client.algod,\n    indexer_client=localnet.client.indexer,  # only needed when sync_behaviour=\"catchup-with-indexer\"\n)\n\n# Set up subscription(s)\ndef on_filter1(transaction: sub.SubscribedTransaction, filter_name: str) -\u003e None:\n    ...\n\nsubscriber.on(\"filter1\", on_filter1)\n\n# Either: Start the subscriber (if in long-running process)\nsubscriber.start()\n\n# OR: Poll the subscriber (if in cron job / periodic lambda)\nsubscriber.poll_once()\n```\n\n## Key features\n\n- **Notification _and_ indexing** - You have fine-grained control over the syncing behaviour and can control the number of rounds to sync at a time, the pattern of syncing i.e. start from the beginning of the chain, or start from the tip; drop stale records if your service can't keep up or keep syncing from where you are up to; etc.\n- **Low latency processing** - When your service has caught up to the tip of the chain it can optionally wait for new rounds so you have a low latency reaction to a new round occurring\n- **Watermarking and resilience** - You can create reliable syncing / indexing services through a simple round watermarking capability that allows you to create resilient syncing services that can recover from an outage\n- **Extensive subscription filtering** - You can filter by transaction type, sender, receiver, note prefix, apps (ID, creation, on complete, ARC-4 method signature, call arguments, ARC-28 events), assets (ID, creation, amount transferred range), transfers (amount transferred range) and balance changes (algo and assets)\n- **ARC-28 event subscription support** - You can subscribe to ARC-28 events for a smart contract\n- **Balance change support** - Subscribed transactions will have all algo and asset balance changes calculated for you and you can also subscribe to balance changes that meet certain criteria\n- **First-class inner transaction support** - Your filter will find arbitrarily nested inner transactions and return that transaction (indexer can't do this!)\n- **State-proof support** - You can subscribe to state proof transactions\n- **Simple programming model** - It's really easy to use and consume through easy to use, type-safe methods and objects and subscribed transactions have a comprehensive and familiar model type with all relevant/useful information about that transaction (including things like transaction id, round number, created asset/app id, app logs, etc.) modelled on the indexer data model (which is used regardless of whether the transactions come from indexer or algod so it's a consistent experience)\n- **Easy to deploy** - You have full control over how you want to deploy and use the subscriber; it will work with whatever persistence (e.g. sql, no-sql, etc.), queuing/messaging (e.g. queues, topics, buses, web hooks, web sockets) and compute (e.g. serverless periodic lambdas, continually running containers, virtual machines, etc.) services you want to use\n- **Fast initial index** - There is an indexer catch up mode that allows you to use indexer to catch up to the tip of the chain in seconds or minutes rather than days; alternatively, if you prefer to just use algod and not indexer that option is available too!\n\n## Balance change notes\n\nThe balance change semantics work mostly as expected, however the semantics around asset creation and destruction warrants further clarification.\n\nWhen an asset is created, the full asset supply is attributed to the asset creators account.\n\nThe balance change for an asset create transaction will be as below:\n\n```py\nimport algokit_subscriber as sub\n\nsub.BalanceChange(\n    address=\"VIDHG4SYANCP2GUQXXSFSNBPJWS4TAQSI3GH4GYO54FSYPDIBYPMSF7HBY\",  # The asset creator\n    asset_id=2391,  # The created asset id\n    amount=100000,  # Full asset supply of the created asset\n    roles=[sub.BalanceChangeRole.AssetCreator],\n)\n```\n\nWhen an asset is destroyed, the full asset supply must be in the asset creators account and the asset manager must send the destroy transaction.\nUnfortunately we cannot determine the asset creator or full asset supply from the transaction data. As a result the balance change will always be attributed to the asset manager and will have a 0 amount.\nIf you need to account for the asset supply being destroyed from the creators account, you'll need to handle this separately.\n\nThe balance change for an asset destroy transaction will be as below:\n\n```python\nimport algokit_subscriber as sub\n\nsub.BalanceChange(\n    address=\"PIDHG4SYANCP2GUQXXSFSNBPJWS4TAQSI3GH4GYO54FSYPDIBYPMSF7HBY\",  # The asset destroyer, which will always be the asset manager\n    asset_id=2391,  # The destroyed asset id\n    amount=0,  # This value will always be 0\n    roles=[sub.BalanceChangeRole.AssetDestroyer],\n)\n```\n\n## Examples\n\n### Data History Museum index\n\nThe following code, when algod is pointed to TestNet, will find all transactions emitted by the [Data History Museum](https://datahistory.org) since the beginning of time in _seconds_ and then find them in real-time as they emerge on the chain.\n\nThe watermark is stored in-memory so this particular example is not resilient to restarts. To change that you can implement proper persistence of the watermark.\n\n```python\nimport algokit_subscriber as sub\nfrom algokit_utils import AlgorandClient\n\nalgorand = AlgorandClient.testnet()\n\n\nsubscriber = sub.AlgorandSubscriber(\n    config=sub.AlgorandSubscriberConfig(\n        filters=[\n            # Match asset configuration transactions from DHM creator account\n            sub.SubscriberConfigFilter(\n                name=\"dhm-asset\",\n                type=\"acfg\",\n                sender=\"ER7AMZRPD5KDVFWTUUVOADSOWM4RQKEEV2EDYRVSA757UHXOIEKGMBQIVU\",\n            ),\n        ],\n        frequency_in_seconds=5,\n        max_rounds_to_sync=100,\n        sync_behaviour=\"catchup-with-indexer\",\n        watermark_persistence=sub.in_memory_watermark(),\n    ),\n    algod_client=algorand.client.algod,\n    indexer_client=algorand.client.indexer,\n)\n\n\ndef process_dhm_assets(transactions: list[sub.SubscribedTransaction], filter_name: str) -\u003e None:\n    print(f\"Received {len(transactions)} asset changes\")\n    # ... do stuff with the transactions\n\n\n# Attach our callback to the 'dhm-asset' filter\nsubscriber.on_batch(\"dhm-asset\", process_dhm_assets)\n\n\ndef handle_error(error: Exception) -\u003e None:\n    print(f\"An error occurred: {error}\")\n\n\n# Attach the error handler\nsubscriber.on_error(handle_error)\n\n# Start the subscriber\nsubscriber.start()\n```\n\n### USDC real-time monitoring\n\nThe following code, when algod is pointed to MainNet, will find all transfers of [USDC](https://www.circle.com/en/usdc-multichain/algorand) that are greater than $1 and it will poll every 1s for new transfers.\n\n```python\nimport algokit_subscriber as sub\nfrom algokit_utils import AlgorandClient\n\nalgorand = AlgorandClient.mainnet()\n\nsubscriber = sub.AlgorandSubscriber(\n    config=sub.AlgorandSubscriberConfig(\n        filters=[\n            sub.SubscriberConfigFilter(\n                name=\"usdc\",\n                type=\"axfer\",\n                asset_id=31566704,  # MainNet: USDC\n                min_amount=1_000_000,  # $1\n            ),\n        ],\n        wait_for_block_when_at_tip=True,\n        sync_behaviour=\"skip-sync-newest\",\n        watermark_persistence=sub.in_memory_watermark(),\n    ),\n    algod_client=algorand.client.algod,\n)\n\n\ndef process_usdc_transfer(transfer: sub.SubscribedTransaction, filter_name: str) -\u003e None:\n    axfer = transfer.asset_transfer_transaction\n    if axfer is None:\n        return\n    amount = axfer.amount / 1_000_000\n    print(f\"{transfer.sender} sent {axfer.receiver} USDC${amount:.2f} in transaction {transfer.id_}\")\n\n\n# Attach our callback to the 'usdc' filter\nsubscriber.on(\"usdc\", process_usdc_transfer)\n\n\ndef handle_error(error: Exception) -\u003e None:\n    print(f\"An error occurred: {error}\")\n\n\n# Attach the error handler\nsubscriber.on_error(handle_error)\n\n# Start the subscriber\nsubscriber.start()\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falgorandfoundation%2Falgokit-subscriber-py","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falgorandfoundation%2Falgokit-subscriber-py","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falgorandfoundation%2Falgokit-subscriber-py/lists"}