Practical overview
When it fits
Use it when Python code needs to read Substrate storage or build runtime-aware transaction and data workflows through a light client or node RPC connection.
Who it is for
- Python developers building scripts or applications for Substrate-based chains
- Developers who need to query account or other on-chain storage
- Teams building runtime-aware tools or handling SCALE data and extrinsics
Documented uses
- Query account balances and other Substrate storage
- Compose, sign and submit extrinsics
- Encode and decode SCALE data
- Use runtime metadata and properties in Python tools
Requirements & limits
The repository specifies an Apache-2.0 license. Installation is documented with pip using the package name `substrate-interface`.
- Choose between the documented embedded light-client and node RPC connection patterns based on how the application will connect.
- Automatic detection of properties such as SS58 format is described for most MetadataV14-and-later runtimes; older or developing runtimes may need manual configuration.
- The documented transfer flow requires a keypair to sign the extrinsic.
Check current requirements in the official documentation. Source-based guidance does not mean OpenViST has run or independently tested this project.
Connect a Python script to a Substrate node
Install the library and initialize a connection using either an embedded light client or a node RPC endpoint.
Before you start
- Python environment with pip
- A chain specification for the embedded light-client option, or a node RPC endpoint for the RPC option
Steps
Install the package with the command below.
pip install substrate-interfaceInitialize
SubstrateInterfacewith a chain specification and relay chain specifications for the embedded light-client option, or provide a node WebSocket URL such asws://127.0.0.1:9944.For older runtimes or runtimes under development, set the SS58 format and other properties manually as needed.
Expected outcome
A `SubstrateInterface` instance initialized through one of the documented connection methods.
Guide limitations
- Automatic property detection is described for most MetadataV14-and-later runtimes; older or developing runtimes may need manual settings.
Query an account balance and submit a transfer extrinsic
Use the documented interface to read an account’s free balance and build, sign and submit a Balances transfer.
Before you start
- An initialized
SubstrateInterfaceconnection - Account address and transfer destination
- A keypair available to sign the extrinsic
Steps
Query the
System.Accountstorage entry for the account and readresult.value['data']['free'].Compose a
Balances.transfercall with the destination and value.Create a signed extrinsic from the call and keypair, then submit it with
wait_for_inclusion=True.Read the returned receipt’s extrinsic and block hashes.
Expected outcome
The example workflow returns the account’s free-balance value and, after submission, a receipt identifying the extrinsic and block.
Guide limitations
- The README’s signing example uses the development URI
//Alice; it does not document key management for production use. - The example requests inclusion before returning a receipt; it does not establish transaction success in any particular environment.
Sources & review
Source record details
- Source availability
- Active
- Sources checked
- 10 October 2026
- Original website title
- JAMdotTech/py-polkadot-sdk · Official homepage title · retained in its source language