Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


A Python library and utils for the exploration of the Avalanche AVAX network.

Includes an implementation of basic AVAX API calls, offline wallet generator and other utilities.

Documentation and Tutorials

Visit the AVAX section for up to date samples and tutorials.


sudo pip3 install numpy
sudo pip3 install pyopenssl
sudo pip3 install cryptography
sudo pip3 install asn1crypto
sudo pip3 install plyvel

If you plan on generating the python files from api.specification, then requires TatSu

sudo pip install TatSu    

Other required libraries are embedded in this project, under the 3rdparty subdirectory. You can also install these using pip, if you wish to run online:

sudo pip install mnemonic
sudo pip install py-crypto-hd-wallet
sudo pip install bip-utils
sudo pip install pysha3

We've embedded some of the security-related libs so that the project can run offline as much as possible, if you choose to.

Specifically, this project includes code from the following libraries under the 3rdparty/ subdirectory:


avax-python runs from its downloaded location.

If a git client is not available, then you may download a ZIP archive instead.

For the online functions, Avalanchego must be running and listening on localhost port 9650

To use the library and utils, just :

  • Clone the git repo
  • Set the environment
  • Build and install pysha3

In short:

git clone
cd avax-python/

pysha3 Build

For this step you'll need the Python development headers to be installed.

E.g. on Ubuntu do :

sudo apt-get install python3-dev

Then do:

cd 3rdparty/pysha3
python3 build
sudo python3 install

Offline Scripts

Scripts under the offline/ directory at the project root do not make use of the network.

If you want to be extra safe and perform some actions in an air-gapped environment, then we've grouped the offline scripts inside this directory.

There shouldn't be any network activity coming from any of the scripts in the offline/ subdirectory.


Here are some quick examples of avax-python usage. For more tutorials and complete documentation, visit

List AVAX addresses from a mnemonic phrase [Offline]

python3 offline/wallet/ shoulder man day worry sweet clip outdoor little matter interest option eyebrow asset visa snake find toddler labor puzzle danger quit secret flip foil

# Sample Output:

Launch a subnet validator [Online]

First, generate user/password credentials for your node.

Then, enter your username and password into userpass.txt.

Then run:

python3 <dest_P_addr> <amount_nAVA> 

to send funds from X-Chain to P-Chain, then



Export all Blockchains via IPC [Online]


Generate [Offline]

If you update the api.specification file, then you must regenerate the API metainformation file

To recreate it, run


Implement the AVA API in Any Language

The script reads the API specification in api.specification, the grammar in api.tatsu and generates an AST which can be used to implement the API in any language.

If you need to customize the API, the api.specification file format is very simple.

  • An API endpoint begins a new section. Leave a blank line after the endpoint:/url/here line.
  • See the provided api.specification file and follow the same syntax for function definitions.
  • Functions can be defined over several lines. Don't leave blank lines within a function definition.
  • Leave one blank line after each function definition.

To customize the generator grammar, see the Tatsu documentation

Note that changing the grammar will require changes to The generator uses hard coded offsets which will break if the grammar is modified.

List AVAX Network Nodes

To list AVAX network peers received via P2P communications, run:

python3 bin/

What this script does is install a custom network handler which prints out the content of PeerList messages.

Experimental AVAX Network Node

To run an experimental, passive non-validating node that listens to events on the AVAX network, run :

python3 bin/

This is a work in progress.


Where possible, the python sources follow the same directory structure as the reference Go implementation.

It isn't always possible to keep the code exactly the same, because Go and Python differ in many ways. For example, Go names which are defined in one file and are automatically available across a package in multiple sources, must be explicitly part of some Python module. This leads to some apparent namespace redundancy, like genesis.genesis.FromConfig(...). You can often mitigate this by working the import statement in Python, e.g. from genesis import genesis.

We've tried to make the code as intuitive as possible for those familiar with the Go implementation. Just keep in mind it isn't always possible.


This software released under the MIT License.

See the LICENSE file in this distribution for details.

Embedded Software Licenses

This project includes source code from :

avalanchego : BSD-3-Clause License

mnemonic : MIT License

py_crypto_hd_wallet : MIT License

bip_utils : MIT License


cb58ref : MIT License

bech32 Encoding under wallet/bech32 : by Pieter Wuille, License unspecified, MIT License Presumed

Legal Notices

Avalanche and AVAX are registered trademarks of Ava Labs Inc.

This is not an official Ava Labs project. We are in no way affiliated with Ava Labs.

This free open source software provided for Avalanche AVAX learning and exploration purposes. No warranty is offered, express or implied, as to the suitability or correctness of this code. Cryptocurrency transactions are irreversible. We are not responsible for losses incurred during the use of this software.


Development of avax-python is partly sponsored by

Please help support this Open Source project!

Donate to X-avax1qr6yzjykcjmeflztsgv6y88dl0xnlel3chs3r4

From Snowflake to Avalanche. Per consensum ad astra.


Python tools for the exploration of the Avalanche AVAX network








No packages published