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

Provides asynchronous and synchronous interfaces for querying and interacting with Substrate-based blockchains, using cyscale for SCALE codec decoding.

No—not for new projects. The repository is archived and the project is marked abandoned, meaning no active maintenance, security updates, or bug fixes are forthcoming. While the code may work for stable Substrate networks today, you assume all responsibility for future compatibility and security issues. Consider this only if you are maintaining legacy code that already depends on it and cannot migrate to an actively maintained alternative.

Install

async-substrate-interface on PyPI

pip install async-substrate-interface

uv add async-substrate-interface

poetry add async-substrate-interface

Installing async-substrate-interface

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.

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())

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.

Verify before relying

• Whether the abandoned status affects real-world reliability for stable Substrate networks or if the API remains functional despite no active maintenance.
• Performance characteristics of cyscale-based SCALE decoding compared to alternatives in production workloads.
• Compatibility with recent Substrate runtime versions and whether breaking changes have occurred since the last release on 2026-06-29.

Package facts

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

Keywords: substrate, development, bittensor

Tags

More Libraries packages