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:
| Area | What you get |
|---|---|
| Keys and cryptography | PrivateKey and PublicKey, BIP32, BIP39 and BIP44 HD wallets, BRC-42BSV Key Derivation Scheme key derivation, ECIES, Schnorr signatures and signed messages |
| Script and templates | Script, a script interpreter, and the P2PKH, P2PK, OP_RETURN and bare multisig templates |
| Transactions and fees | Transaction, TransactionInput and TransactionOutput, with fee calculation and change outputs |
| Proofs | SPVSimplified Payment Verification checks with BEEFBackground Evaluation Extended Format (BRC-62), a transaction sent with its proofs and Merkle proofs |
| Broadcasting and chain tracking | Broadcasters such as ARCAuthoritative Response Component, a transaction processor. BSV Broadcaster replaces it. and chain trackers |
| Wallet and authentication | Wallet substrates and serializers, and peer authentication with certificates |
| Overlay services and identity | Lookup 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-sdkpip 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.
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.pyThe 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: TrueThese parts of sign.py need a closer look:
priv_key.address(network=Network.TESTNET)derives a testnet address from the key. If you leave outnetwork, 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=Truemakes the output take whatever the input holds beyond the fee, andtx.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 insideasyncio.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:
| Task | Script |
|---|---|
| Create HD wallets from a mnemonic | hd.py |
| Encrypt and decrypt with ECIES | ecies.py |
| Sign and verify a text message | sign_text.py |
| Derive keys with BRC-42 | type_42.py |
| Split a private key into 5 shares, any 3 of which recover it | threshold_signature.py |
| Write a custom fee model | custom_fee_model.py |
Related articles
To learn more about the SDKs on the BSV blockchain, review these articles: