Metadata-Version: 2.4
Name: btclib
Version: 2026.8.7
Summary: A library for 'bitcoin cryptography'
Author-email: The btclib developers <devs@btclib.org>
License-Expression: MIT
Project-URL: Homepage, https://btclib.org
Project-URL: Download, https://github.com/btclib-org/btclib/releases
Project-URL: Documentation, https://btclib.readthedocs.io/
Project-URL: GitHub, https://github.com/btclib-org/btclib
Project-URL: Issues, https://github.com/btclib-org/btclib/issues
Project-URL: Pull Requests, https://github.com/btclib-org/btclib/pulls
Keywords: bitcoin,cryptography,elliptic-curves,ecdsa,schnorr,RFC-6979,bip32,bip39,electrum,base58,bech32,segwit,message-signing,bip340
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS.md
Requires-Dist: btclib_libsecp256k1>=0.7.1.2
Requires-Dist: bitcoin-core-rpc>=2026.8.7
Dynamic: license-file

# A Python library for 'bitcoin cryptography'

<!-- markdownlint-disable MD013 -->
| | |
| --- | --- |
| Project | [![status](https://img.shields.io/pypi/status/btclib.svg)](https://pypi.python.org/pypi/btclib/) [![license](https://img.shields.io/github/license/btclib-org/btclib.svg)](https://github.com/btclib-org/btclib/blob/master/LICENSE) |
| Package | [![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv) [![calver: yyy.m.d](https://img.shields.io/badge/cal_ver-yyyy.m.d-1674b1.svg?logo=calver)](https://calver.org/) [![pypi](https://img.shields.io/pypi/v/btclib.svg?logo=pypi)](https://pypi.python.org/pypi/btclib/) [![downloads](https://static.pepy.tech/badge/btclib)](https://pepy.tech/project/btclib) |
| Supported platforms | [![python](https://img.shields.io/pypi/pyversions/btclib.svg?logo=python)](https://pypi.python.org/pypi/btclib/) |
| Formatting standards | [![format: ruff](https://img.shields.io/badge/format-ruff-yellowgreen.svg?logo=ruff)](https://docs.astral.sh/ruff/formatter/) [![lint: markdownlint-cli2](https://img.shields.io/badge/lint-markdownlint--cli2-yellowgreen.svg?logo=markdown)](https://github.com/DavidAnson/markdownlint-cli2) |
| Coding standards | [![lint: ruff](https://img.shields.io/badge/lint-ruff-yellowgreen.svg?logo=ruff)](https://docs.astral.sh/ruff/) |
| Type checking | [![type check: mypy](https://img.shields.io/badge/type_check-mypy-yellowgreen.svg?logo=mypy)](https://mypy-lang.org/) |
| Documentation | [![docs](https://readthedocs.org/projects/btclib/badge/?version=latest)](https://btclib.readthedocs.io) [![lint: ruff](https://img.shields.io/badge/docstrings-ruff-yellowgreen.svg?logo=ruff)](https://docs.astral.sh/ruff/rules/#pydocstyle-d) |
| CI/CD | [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit) [![pre-commit.ci status](https://results.pre-commit.ci/badge/github/btclib-org/btclib/master.svg)](https://results.pre-commit.ci/latest/github/btclib-org/btclib/master) [![lint](https://github.com/btclib-org/btclib/actions/workflows/lint.yml/badge.svg)](https://github.com/btclib-org/btclib/actions/workflows/lint.yml) [![test](https://github.com/btclib-org/btclib/actions/workflows/test.yml/badge.svg)](https://github.com/btclib-org/btclib/actions/workflows/test.yml) |
| Conversations | [![slack](https://img.shields.io/badge/slack-btclib_dev-white.svg?logo=slack)](https://bbt-training.slack.com/messages/C01CCJ85AES) |

[Browse GitHub Code Repository](https://github.com/btclib-org/btclib/)

---
<!-- markdownlint-enable MD013 -->

[btclib](https://btclib.org) is a
Python3 [type annotated](https://docs.python.org/3/library/typing.html)
library intended for teaching, learning, and using bitcoin;
the focus is on elliptic curve cryptography and bitcoin's blockchain.

The test suite covers virtually the whole code base — a coverage
floor the build enforces — and reproduces the published vectors of
the BIPs, of RFC 6979, and of Bitcoin Core.

Originally developed for the
*[Bitcoin and Blockchain Technology](https://www.ametrano.net/bbt/)*
course at the University of Milano-Bicocca,
btclib is not intended for production environments:
it is often refactored for improved clarity,
without care for backward compatibility; moreover,
some of its algorithms could be broken using side-channel attacks.

The library is not limited to the bitcoin elliptic curve secp256k1;
for that curve, though, it always relies on
[btclib_libsecp256k1](https://github.com/btclib-org/btclib-libsecp256k1),
FFI bindings to
[libsecp256k1](https://github.com/bitcoin-core/secp256k1)
(the optimized C library used by Bitcoin Core):
they are a required dependency, not an optional accelerator, so
installing btclib needs either one of their wheels or a C toolchain to
build them. The Python implementation is what every other curve uses,
and the test suite validates it against the bindings: it is libsecp256k1
that says what the right answer is, being the implementation bitcoin
consensus itself relies on.

Included features are:

- modulo algebra functions (gcd, inverse, legendre symbol, square root)
- octets / integer / point / var_int / var_bytes helper functions
- elliptic curve class
    - fast algebra implemented using Jacobian coordinates
    - double scalar multiplication (Straus's algorithm, also known as
      Shamir's trick)
    - multi scalar multiplication (Bos-coster's algorithm)
    - point symmetry solution: odd/even, low/high, and quadratic residue
    - elliptic curves: SEC 1 v1 and v2, NIST, Brainpool, and
      low cardinality test curves
- ECDSA signature with (transaction) DER encoding
- ECDSA signature with (message) compact encoding: standard p2pkh and
  [BIP137](https://github.com/bitcoin/bips/blob/master/bip-0137.mediawiki)/[Electrum](https://electrum.org/#home)
  extensions to p2wpkh and p2wpkh-p2sh
- [RFC 6979](https://www.rfc-editor.org/rfc/rfc6979.html) for deterministic signature
  schemes
- EC Schnorr signature (according to
  [BIP340](https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki)
  bitcoin standardization)
    - batch validation
    - threshold signature (see test-suite)
    - [MuSig2](https://github.com/bitcoin/bips/blob/master/bip-0327.mediawiki)
      multi-signature: key aggregation with plain and x-only tweaking,
      nonce aggregation, partial signatures and their aggregation, one
      primitive per round of the protocol
- Borromean ring signature
- Sign-to-contract commitment
- Diffie-Hellman
- Pedersen commitment
- Base58 encoding/decoding
- p2pkh/p2sh addresses and WIFs
- Bech32 encoding/decoding
- p2wpkh/p2wsh native segwit addresses and their legacy p2sh-wrapped versions
- [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki)
  hierarchical deterministic key chains
- [SLIP132](https://github.com/satoshilabs/slips/blob/master/slip-0132.md)
  key versions (xprv, yprv, zprv, Yprv, Zprv, tprv, uprv, vprv, and Uprv)
  with corresponding mapping to
  p2pkh/p2sh, p2wpkh-p2sh, p2wpkh, p2wsh-p2sh, p2wsh and p2tr addresses
- [BIP44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki)
  address from an extended key and a
  `m/purpose'/coin_type'/account'/change/address_index` path, the purpose
  selecting the encoding: 44 p2pkh, 49 p2wpkh-p2sh, 84 p2wpkh (BIP84),
  86 p2tr (BIP86)
- [BIP39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki)
  mnemonic for generating deterministic keys, in the twelve wordlists of
  the reference implementation, with the language read off the words
- [Electrum](https://electrum.org/#home) standard for mnemonic, in the
  five wordlists Electrum reads
- [SLIP39](https://github.com/satoshilabs/slips/blob/master/slip-0039.md)
  Shamir backup: a master secret split into mnemonic shares, of which a
  threshold number recovers it
- Script encoding/decoding
- nulldata, p2pk, p2ms, p2pkh, p2sh, p2wpkh, p2wsh and p2tr ScriptPubKeys
- BlockHeader and Block data classes
- OutPoint, TxIn, TxOut, and TX data classes
- legacy, segwit_v0 and taproot transaction hash signatures
- [BIP174](https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki)
  partially signed bitcoin transactions (PSBT):
  PsbtIn, PsbtOut, and Psbt data classes
- [BIP370](https://github.com/bitcoin/bips/blob/master/bip-0370.mediawiki)
  PSBT version 2, where the unsigned transaction is computed from the
  fields rather than carried as one: the lock time its inputs require,
  the identifier that ignores their sequences, the modifiable flags a
  Constructor must obey, and conversion either way
- fee rates carrying their unit (sat/kvB and sat/vB), the fee a virtual
  size owes at one, and the dust threshold of any output type — computed
  the way Bitcoin Core computes it, rather than tabulated
- keystore: the addresses an extended key or a set of individual keys has
  handed out, the derivation path of each, and the private key that signs
  for one — which is what `sign(address, msg)` needs and what a message
  signature by address had no way to find
- a chain backend behind one interface — a transaction by id, the output
  an outpoint names, the chain tip — over a full node's JSON-RPC or a
  block explorer's HTTP api, written on the standard library so that it
  adds no dependency

---

## Module layout

Three pairs of modules are one idea split in two, and each split runs one
way only. Knowing which half is which is most of finding your way around:

| the codec / the arithmetic | the bitcoin semantics on top |
| --- | --- |
| `btclib.curves` — `Curve`, `mult` | `btclib.ecc` — `dsa`, `ssa`, `bms` |
| `btclib.base58` — the encoding | `btclib.b58` — WIF, p2pkh, p2sh |
| `btclib.bech32` — the encoding | `btclib.b32` — p2wpkh, p2wsh, p2tr |

The right column imports the left one; the left never imports the right.

So `from btclib.ecc import dsa` for a signature and
`from btclib.curves import mult` for a point multiplication; `btclib.b58`
for an address and `btclib.base58` only if you want the encoding on its
own. It is the split the standard library draws between `base64` and
whatever uses it. Each of the six modules repeats the rule in its own
docstring.

The rest, roughly bottom-up: `to_prv_key` and `to_pub_key` accept any key
representation and hand back one; `bip32` and `mnemonic` derive keys;
`script`, `tx`, `block` and `psbt` build and validate what goes on the
chain. `bip21` parses and builds `bitcoin:` payment URIs, and sits on top
of everything: it imports `b58`, `b32`, `amount` and `network`, and nothing
in the library imports it. `bip44` is up there as well, and for the same
reason: an address from an extended key and a derivation path is `bip32`
and `script.taproot` and both address encodings composed, so it imports
all four and nothing imports it. `keystore` is one level above even that:
it remembers which addresses `bip44` has handed out and signs for one
with `ecc.bms`, so it imports `bip44` and nothing imports it. `fetch`
sits up there too, and is the one package that goes out to the network:
nothing below it imports it.

The Bitcoin Core rpc client `fetch` speaks through is not in that stack at
all: it is
[bitcoin-core-rpc](https://github.com/btclib-org/btclib-bitcoin-core-rpc),
a package of its own that btclib depends on. One file with nothing but the
standard library behind it, installable or copyable, and usable without
btclib by anyone who wants a node client and no bitcoin library. What
btclib adds on top is `btclib.fetch`: the answers turned into `Tx` and
`TxOut`, and the chain the node reports checked against the network those
are labelled for.

The dependency stops at `btclib/fetch/`. The exceptions a `Fetcher` raises
are `btclib.exceptions`' own — the package declares its own `FetchError`,
importing nothing of btclib's being what lets its one file be vendored, and
`btclib.fetch.fetcher.client_errors` re-raises them as btclib's with the
`status` and the `code` carried across. So an `except FetchError` written
against btclib catches what a fetcher raises, and no module outside that
package loads `urllib.request` to find out. Nothing connects to anything
either: constructing a client opens no socket, and the first call is what
does.

---

To install (and/or upgrade) btclib:

```shell
python -m pip install --upgrade btclib
```

You might want to install btclib into a
Python virtual environment; e.g. from the root folder:

Shell:

```shell
python -m venv venv_btclib
source ./venv_btclib/bin/activate
python -m pip install --upgrade btclib
```

Windows CMD or PowerShell:

```powershell
python -m venv venv_btclib
.\venv_btclib\Scripts\activate
python -m pip install --upgrade btclib
```

Windows Git bash shell:

```bash
python -m venv venv_btclib
cd ./venv_btclib/Scripts
. activate
cd ../..
python -m pip install --upgrade btclib
```

See [CONTRIBUTING](./CONTRIBUTING.md) if you are interested
in btclib development.

See [SECURITY](./SECURITY.md) if you have found a security vulnerability.
