---
id: substrate-interface
version: "1.8.1"
license: unclear
license_treatment: permissive
maintenance: active
---

# substrate-interface — Library for interfacing with a Substrate node

License: permissive · Maintenance: active · Downloads: 261.7K/mo

## What it is and what it does

substrate-interface is a Python client library for interacting with Substrate-based blockchains like Polkadot and Kusama. It provides methods to query on-chain storage, compose and sign transactions (extrinsics), and handle the SCALE codec used by Substrate runtimes. The library can connect either to a remote node via WebSocket RPC or use an embedded light client.

The package wraps low-level blockchain operations into higher-level Python abstractions, automatically discovering runtime metadata and chain properties from the connected node. It handles cryptographic signing via keypairs, manages account balances and state queries, and abstracts away the complexity of SCALE encoding for common operations. With 16 runtime dependencies including cryptographic libraries (ecdsa, PyNaCl, pycryptodome) and codec tools (scalecodec, xxhash), it provides a complete toolkit for Substrate development.

Use it for:

- Query account balances and storage state from a Polkadot or Kusama node
- Compose and submit signed transactions (extrinsics) to transfer funds or call runtime functions
- Build automation scripts that interact with Substrate-based chains programmatically
- Decode and encode SCALE-formatted data for custom runtime interactions
- Monitor on-chain events and state changes via RPC subscriptions

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Interfaces with Substrate blockchain nodes to query storage, compose and submit transactions, and handle SCALE encoding/decoding for Polkadot, Kusama, and other Substrate-based networks.

Yes. Active maintenance, no known vulnerabilities, permissive license, and low install friction make this a solid choice for Substrate blockchain development. The 16 dependencies are well-established cryptographic and networking libraries. Install if you need to interact with Polkadot, Kusama, or other Substrate chains from Python.

## Install

pip install substrate-interface
uv add substrate-interface
poetry add substrate-interface

## Installing substrate-interface

Before you install: Low friction installation with a pure-Python wheel. Actively maintained with recent commits and no known vulnerabilities. Supports Python 3.7 through 3.11.

License in practice: Licensed under Apache Software License (permissive), allowing commercial and private use with minimal restrictions.

Quickstart:

pip install substrate-interface

from substrate_interface import SubstrateInterface

substrate = SubstrateInterface(url="ws://127.0.0.1:9944")
result = substrate.query('System', 'Account', ['F4xQKRUagnSGjFqafyhajLs94e7Vvzvr8ebwYJceKpr8R7T'])
print(result.value['data']['free'])

Requires a running Substrate node RPC endpoint (local or remote) or uses embedded light client via smoldot-light; WebSocket connectivity needed.

Verify before relying:

- Performance characteristics when querying large datasets or high-frequency RPC calls
- Compatibility scope with runtimes older than MetadataV14 or under active development

## Package facts

- License: not declared (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 261.7K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

substrate blockchain interface, polkadot python client, substrate rpc library, scale encoding decoding, kusama node interaction, blockchain, cryptography, rpc-client

[View on SkillFed](https://skillfed.io/packages/substrate-interface) · [View on PyPI](https://pypi.org/project/substrate-interface/)