BSV blockchainBSV blockchain

Use the Python SDK

Use bsv-sdk to build keys, scripts, transactions and proofs for the BSV blockchain in Python, from a signed P2PKHPay to Public Key Hash, the standard script that locks coins to an address transaction up to peer authentication and overlay tools. The docs and examples live in the Python repositories, and this page links them.

What the SDK includes

The package is bsv-sdk on PyPI, and you import it as bsv:

AreaWhat you get
Keys and cryptographyPrivateKey and PublicKey, BIP32, BIP39 and BIP44 HD wallets, BRC-42BSV Key Derivation Scheme key derivation, ECIES, Schnorr signatures and signed messages
Script and templatesScript, a script interpreter, and the P2PKH, P2PK, OP_RETURN and bare multisig templates
Transactions and feesTransaction, TransactionInput and TransactionOutput, with fee calculation and change outputs
ProofsSPVSimplified Payment Verification checks with BEEFBackground Evaluation Extended Format (BRC-62), a transaction sent with its proofs and Merkle proofs
Broadcasting and chain trackingBroadcasters such as ARCAuthoritative Response Component, a transaction processor. BSV Broadcaster replaces it. and chain trackers
Wallet and authenticationWallet substrates and serializers, and peer authentication with certificates
Overlay services and identityLookup and broadcast tools for overlay servicesBuilt from topic managers, which decide what is admitted, and lookup services, which query what was admitted., an identity client and a registry client

Get started

Install the SDK, then run a first script that signs a transaction and checks its scripts, without touching the network.

Install the SDK

This page was written against bsv-sdk 2.4.0, which needs Python 3.10 or newer. Install it with pip:

pip install bsv-sdk

pip also installs pycryptodomex, requests, aiohttp and typing_extensions.

Create sign.py

Create sign.py in your project folder. The script builds and signs a transaction on your computer, with a key, a locking scriptThe part of a transaction output that sets the condition to spend it, an input, an output and a signature. It makes no network call and spends no coins.

The script generates a private key on each run and never saves it. Keep a private key that holds real funds out of your source code and out of version control.

sign.py
import asyncio

from bsv import (
    Network,
    P2PKH,
    PrivateKey,
    SatoshisPerKilobyte,
    Transaction,
    TransactionInput,
    TransactionOutput,
)


async def main():
    priv_key = PrivateKey()
    address = priv_key.address(network=Network.TESTNET)

    source_tx = Transaction(
        [],
        [TransactionOutput(locking_script=P2PKH().lock(address), satoshis=10000)],
    )

    tx_input = TransactionInput(
        source_transaction=source_tx,
        source_txid=source_tx.txid(),
        source_output_index=0,
        unlocking_script_template=P2PKH().unlock(priv_key),
    )
    tx_output = TransactionOutput(locking_script=P2PKH().lock(address), change=True)
    tx = Transaction([tx_input], [tx_output], version=1)

    tx.fee(SatoshisPerKilobyte(100))
    tx.sign()

    print("Transaction ID:", tx.txid())
    print("Raw hex:", tx.hex())
    print("Scripts valid:", await tx.verify(scripts_only=True))


asyncio.run(main())

Run the script

Run it from the same folder:

python sign.py

The script prints the transaction ID, the signed transaction in hex, and the result of the script check. The first two change on every run, because the key is new each time:

Transaction ID: 0ccd280ed6b5b4d49d7ac4593f3356b4a186fbca25a6996a66807b4c6c7fef78
Raw hex: 0100000001d92fed6178372d43d2c1f6c5cc3b7d92d95872e0c7bdeba481156e00220c3c86000000006b48...
Scripts valid: True

These parts of sign.py need a closer look:

  • priv_key.address(network=Network.TESTNET) derives a testnet address from the key. If you leave out network, the address is a Mainnet address.
  • The script builds its own source transaction with one output of 10,000 satoshisThe smallest unit of BitcoinSV (BSV). 100,000,000 satoshis make 1 BSV., so the input has something to spend. To spend a real output, load the transaction that created one of your own UTXOsUnspent transaction output instead.
  • change=True makes the output take whatever the input holds beyond the fee, and tx.fee(SatoshisPerKilobyte(100)) calculates that fee at 100 satoshis per kilobyte. The fee model is passed in on purpose: tx.fee() with no argument asks the live ARC policy over the network.
  • verify(scripts_only=True) runs the locking and unlocking scripts against each other, with no Merkle proof and no network. It is async, so the script runs inside asyncio.run.

A broadcast transaction cannot be undone, and tx.broadcast() with no argument sends to Mainnet, through ARC at GorillaPool. Test on testnet before you use Mainnet.

To send a transaction, call await tx.broadcast(). The transaction in sign.py cannot be broadcast, because it spends an output that exists only in the script. To broadcast one, build the input from an output you own on testnet. For the endpoints and the broadcaster BSV Association runs, see Broadcast transactions with BSV Broadcaster.

Find the docs and examples

The docs and examples live in the Python repositories, next to the code.

Docs and repositories

Start from these repositories and docs:

  • py-sdk, with its README and releases.
  • py-sdk docs, with a step-by-step tutorial, fee models, and ARC and ArcadeThe former name of BSV Broadcaster, kept in the Python SDK class Arcade broadcasting.
  • bsv-sdk on PyPI, for versions and release history.
  • py-wallet-toolbox, with its docs and examples, for building BRC-100BSV Request for Comments 100, the standard interface between apps and wallets wallets in Python.

Examples you can run

These single-file scripts in the examples folder run on your computer without a network:

TaskScript
Create HD wallets from a mnemonichd.py
Encrypt and decrypt with ECIESecies.py
Sign and verify a text messagesign_text.py
Derive keys with BRC-42type_42.py
Split a private key into 5 shares, any 3 of which recover itthreshold_signature.py
Write a custom fee modelcustom_fee_model.py

To learn more about the SDKs on the BSV blockchain, review these articles: