Welcome to XChainPy2’s documentation!

XChainPy2 is a collection of Python libraries for interacting with various blockchains. It is a freestyle port of XChainJS library, which was written in JavaScript. The goal of XChainPy2 is to provide a simple, consistent interface for interacting with different blockchains, making it easy to build cross-chain applications.

Danger

XChainPy2 is still in development and should be considered alpha software. If you intend to use the library for real funds, do so with great caution! Disclaimer! The authors are not responsible for lost funds! Please verify the code before using it in a production environment.

The source code is available on GitHub: https://github.com/tirinox/xchainpy. Feel free to contribute to the project by opening issues or pull requests.

Warning

This documentation is also in development and may not be complete or accurate. Please refer to the source code for the most up-to-date information.

Quick Start example

See how easy it is to swap assets using XChainPy2:

import asyncio

from xchainpy2_thorchain_amm import THORChainAMM, NO_SWAP_LIMIT, FeeOption, GasOptions
from xchainpy2_wallet import Wallet
from xchainpy2_thorchain_query import TxDetails
from xchainpy2_utils import Chain, AssetAVAX


async def main():
    phrase = "your secret phrase here"
    wallet = Wallet(phrase)

    amm = THORChainAMM(wallet)

    bsc = wallet.get_client(Chain.BinanceSmartChain)
    avax = wallet.get_client(Chain.Avalanche)

    balance_bsc = await bsc.get_gas_balance()
    balance_avax = await avax.get_gas_balance()
    print(f"BSC balance: {balance_bsc} and AVAX balance: {balance_avax}")

    tx_hash = await amm.do_swap(
        input_amount=bsc.gas_amount(1.0),  # 1 BNB
        destination_asset=AssetAVAX,
        tolerance_bps=NO_SWAP_LIMIT,
        gas_options=GasOptions.automatic(FeeOption.FAST),
    )

    print(f"Swap TX hash {bsc.get_explorer_tx_url(tx_hash)}")

    await bsc.wait_for_transaction(tx_hash)

    tracker = amm.tracker()
    async for status in tracker.poll(tx_hash):
        status: TxDetails
        print(f'Status: {status.status}; stage: {status.stage}')

    await amm.close()


if __name__ == "__main__":
    asyncio.run(main())

More examples

More examples can be found in the examples directory. https://github.com/tirinox/xchainpy/tree/main/examples

Modular design

The library is designed to be modular, so you can use only the parts you need.

It contains the following packages.

Essential utilities:

  1. xchainpy2_utils (Utils, Amount, Asset) - A collection of utility functions and classes. It also has widely used Asset, Amount and CryptoAmount classes.

  2. xchainpy2_crypto (Crypto utils) - A collection of cryptographic functions. Keystore, mnemonic, etc.

  3. xchainpy2_client (XChainPy Base Chain Client) - Base class for blockchain clients. It provides a common interface for interacting with different blockchains. Normally, you will not use this module directly, but use the specific blockchain client modules.

AMM and data providers:

  1. xchainpy2_thorchain_query (THORChain query) - THORChain query module to access the APIs and quote swaps.

  2. xchainpy2_thorchain_amm (THORChain AMM) - THORChain AMM allows you to perform swaps, liquidity actions and all other ThorFi stuff.

  3. xchainpy2_mayanode (Mayanode API connector) - MayaNode client package. Autogenerated from MayaNode API.

  4. xchainpy2_thornode (THORNode API connector) - ThorNode client package. Autogenerated from ThorNode API.

  5. xchainpy2_midgard (Midgard API connector package) - Midgard client package. Autogenerated from Midgard API.

Chain clients:

  1. xchainpy2_thorchain (THORChain client) - THORChain client package. Rune/synth transfer, deposit, etc.

  2. xchainpy2_mayachain (MayaChain client) - MayaChain client package. It has also basic support for MRC-20 and M-NFT tokens.

  3. xchainpy2_ethereum (Ethereum client) - Ethereum client package. It allows you to interact with Ethereum and ERC20 tokens.

  4. xchainpy2_arbitrum (Arbitrum client) - Arbitrum client package.

  5. xchainpy2_avalanche (Avalanche client) - Avalanche client package.

  6. xchainpy2_bsc (Binance Smart Chain client) - Binance Smart Chain client package.

  7. xchainpy2_base (Base client) - Base client package.

  8. xchainpy2_bitcoin (Bitcoin client) - Bitcoin client package.

  9. xchainpy2_litecoin (Litecoin client) - Litecoin client package.

  10. xchainpy2_dogecoin (Dogecoin client) - Dogecoin client package.

  11. xchainpy2_bitcoincash (Bitcoin Cash client) - Bitcoin Cash client package.

  12. xchainpy2_cosmos (Cosmos client) - Cosmos client package.

Wallet:

  1. xchainpy2_wallet - Cross-chain wallet combines multiple clients from the list above into a single object.

Contents: