async-substrate-interface

What it is and what it does

Async-substrate-interface is a Python library that wraps asynchronous and synchronous access to Substrate-based blockchains (like Polkadot). It lets you query chain state, decode data using the SCALE codec, and interact with blockchain RPC endpoints without blocking your event loop. The library provides both an AsyncSubstrateInterface for async/await patterns and a synchronous SubstrateInterface for blocking code, plus specialized variants like DiskCachedAsyncSubstrateInterface that persist query results to disk across runs.

The package depends on aiosqlite, cyscale, typing_extensions, websockets, and xxhash to handle async database operations, fast SCALE decoding, type hints, WebSocket connections, and hashing. It includes three layers of caching—in-memory LRU for both sync and async, plus optional disk persistence—tunable via environment variables. The main gotcha is a namespace conflict with py-scale-codec (scalecodec); the documentation explicitly requires that only cyscale be installed.

Use it for

• Query account balances or storage state from Polkadot or other Substrate networks in an async application without blocking.
• Build a bot or monitoring tool that repeatedly fetches block hashes and runtime metadata, leveraging the built-in LRU and disk caches to reduce network calls.
• Integrate Substrate chain queries into a larger async service (e.g., a web API or background worker) that needs non-blocking blockchain reads.
• Decode SCALE-encoded blockchain data quickly using cyscale's optimized codec instead of the slower py-scale-codec.
• Persist blockchain metadata and query results to disk for tools like btcli that need cache survival across restarts.

Worth the install?

AI-flagged interpretation of the facts on this page. Verify before relying on it.

Install

async-substrate-interface on PyPI

Before you install

Low install friction with a pure-Python wheel distribution. However, the repository is archived and marked abandoned as of the fact sheet date, meaning no active maintenance or security updates are expected going forward.

Requires Python 3.10 or later (supports up to 3.14). If cyscale and py-scale-codec (scalecodec) are both installed, you must uninstall both and reinstall only cyscale to avoid namespace conflicts.

License in practice

MIT License permits free use, modification, and distribution with minimal restrictions. You may use this in commercial projects, but the abandoned status means you assume responsibility for any future fixes or security patches.

Quickstart

pip install async-substrate-interface

from async_substrate_interface import AsyncSubstrateInterface
import asyncio

async def main():
    substrate = AsyncSubstrateInterface(url="wss://rpc.polkadot.io")
    async with substrate:
        result = await substrate.query(
            module='System',
            storage_function='Account',
            params=['5CZs3T15Ky4jch1sUpSFwkUbYEnsCfe1WCY51fH3SPV6NFnf']
        )
        print(result)

asyncio.run(main())

Package facts

Evidence: async_substrate_interface-2.2.1-py3-none-any.whl

Tags

More Libraries packages

See also cyscale · substrate-interface · scalecodec · smoldot-light · bittensor · bittensor-wallet · aiodataloader · async-lru · injective-py · nab-index