{"id":6310,"library":"async-substrate-interface","title":"async-substrate-interface","description":"Asyncio library for interacting with Substrate. It aims to be mostly API-compatible with `py-substrate-interface`. The current version is 1.6.4, with frequent releases, often several per month. It utilizes `bt-decode` for faster SCALE decoding.","status":"active","version":"1.6.4","language":"en","source_language":"en","source_url":"https://github.com/opentensor/async-substrate-interface/","tags":["async","blockchain","substrate","polkadot","web3","cryptocurrency","bittensor"],"install":[{"cmd":"pip install async-substrate-interface","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required Python version range.","package":"python","version":">=3.10,<3.15","optional":false},{"reason":"Used for caching mechanisms.","package":"aiosqlite","version":">=0.21.0,<1.0.0","optional":false},{"reason":"Used for faster SCALE decoding.","package":"bt-decode","version":"==v0.8.0","optional":false},{"reason":"Core library for SCALE codec functionality.","package":"scalecodec","version":"~=1.2.11","optional":false},{"reason":"For WebSocket communication with Substrate nodes.","package":"websockets","version":">=14.1","optional":false},{"reason":"Likely used for hashing in caching or data structures.","package":"xxhash","optional":false}],"imports":[{"symbol":"AsyncSubstrateInterface","correct":"from async_substrate_interface import AsyncSubstrateInterface"}],"quickstart":{"code":"import asyncio\nfrom async_substrate_interface import AsyncSubstrateInterface\n\nasync def main():\n    substrate = AsyncSubstrateInterface(\n        url=\"wss://rpc.polkadot.io\"\n    )\n    async with substrate:\n        result = await substrate.query(\n            module='System',\n            storage_function='Account',\n            params=['5CZs3T15Ky4jch1sUpSFwkUbYEnsCfe1WCY51fH3SPV6NFnf'] # Example address\n        )\n        print(result)\n\nif __name__ == '__main__':\n    asyncio.run(main())","lang":"python","description":"Initializes an `AsyncSubstrateInterface` to connect to a Substrate node (e.g., Polkadot) and performs an asynchronous query for an account's system data. Ensure an `asyncio` event loop is running to execute the main function."},"warnings":[{"fix":"Review the `v1.6.4` changelog and your Substrate node's API documentation for specifics on updated runtime API interactions. Adjust your code to use the modern API.","message":"Version 1.6.4 introduced changes to fix the 'legacy (old) runtimeApi'. Users relying on older runtime API interaction patterns might need to update their code to align with these changes.","severity":"breaking","affected_versions":">=1.6.4"},{"fix":"Upgrade your Python environment to version 3.10, 3.11, 3.12, 3.13, or 3.14. The library currently requires Python `<3.15,>=3.10`.","message":"Support for Python 3.9 was officially removed in version 1.6.2. Attempts to use the library with Python 3.9 or older will likely result in installation or runtime errors.","severity":"deprecated","affected_versions":">=1.6.2"},{"fix":"When migrating from `py-substrate-interface` or developing, carefully review the `async-substrate-interface` documentation and test critical paths to identify any API deviations or behavioral changes.","message":"While designed to be 'mostly API-compatible with py-substrate-interface', the library is explicitly stated as 'about 90% API compatible' and 'its own library'. This implies that subtle differences in API or behavior may exist.","severity":"gotcha","affected_versions":"All"},{"fix":"Be aware of these caching behaviors. Ensure environment variables are set correctly if you wish to override defaults. If using `DiskCachedAsyncSubstrateInterface` with multiple networks, remember that caches are separate per URI, which is usually desired but important to understand.","message":"The library employs various caching mechanisms (in-memory and disk-based via `DiskCachedAsyncSubstrateInterface`). Cache sizes are configurable via environment variables (`SUBSTRATE_CACHE_METHOD_SIZE`, `SUBSTRATE_RUNTIME_CACHE_SIZE`), and disk caching is keyed by the network URI.","severity":"gotcha","affected_versions":"All"},{"fix":"If your application is part of the Bittensor ecosystem, consider leveraging `AsyncSubtensor` for a more integrated and potentially optimized experience. If using `AsyncSubstrateInterface` directly, be mindful of any Bittensor-specific conventions or helper methods you might be missing.","message":"The documentation suggests that while `AsyncSubstrateInterface` can be used directly, it is generally recommended to use it as part of `AsyncSubtensor` when operating within the Bittensor ecosystem.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z"}