coincurve

library21.0.0pypypi✓ verified 25d ago

Coincurve is a Python library providing fast and secure bindings for libsecp256k1, the highly optimized C library used by Bitcoin Core for elliptic curve cryptography operations. It offers a clean, easy-to-use API for tasks like key generation, signing, and verification. The current version is 21.0.0, and it maintains frequent updates to libsecp256k1.

auth-security serialization

pip install coincurve

github ↗package ↗homepage ↗changelog ↗

INSTALL

IMPORT

SIG · COINCURVE

coincurve

auth-securitypythonv21.0.0

Install

1.7s avg

Import

20ms

Disk

18MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v21.0.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.022s · 20.3MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.018s · 21MB

18MB installed

● package 18MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

PrivateKey

✓ from coincurve import PrivateKey

For generating private keys and signing messages.

PublicKey

✓ from coincurve import PublicKey

For handling public keys and verifying signatures.

verify_signature

✓ from coincurve import verify_signature

✗ from coincurve.ecdsa import verify_signature

The function is available directly under the top-level `coincurve` module, not a submodule like `ecdsa`.

This quickstart demonstrates how to generate a secp256k1 private key, derive its public key, sign a hashed message, and verify the signature using `coincurve`. Note that `private_key.sign()` produces a DER-encoded signature expected by `verify_signature`.

import os from coincurve import PrivateKey, verify_signature import hashlib # 1. Generate a new private key (or use an existing one) private_key = PrivateKey() # Get the corresponding public key public_key = private_key.public_key.format(compressed=True) print(f"Public Key (compressed): {public_key.hex()}") # 2. Define a message to sign (must be hashed to 32 bytes for signing) message_str = "Hello, Coincurve!" message_hash = hashlib.sha256(message_str.encode('utf-8')).digest() print(f"Message hash: {message_hash.hex()}") # 3. Sign the message signature = private_key.sign(message_hash) print(f"Signature (DER-encoded): {signature.hex()}") # 4. Verify the signature using the public key and message hash is_valid = verify_signature(signature, message_hash, public_key) if is_valid: print("Signature is valid!") else: print("Signature is INVALID.") # Example of direct verification via PublicKey object (also works) # is_valid_direct = private_key.public_key.verify(signature, message_hash) # print(f"Signature is valid (direct Public Key method): {is_valid_direct}")

Debug

Known issues

breakingPython 3.8 support was dropped in `coincurve` version 21.0.0. Users on Python 3.8 or older must upgrade their Python environment or use an earlier `coincurve` version.

fix

Upgrade Python to 3.9 or newer. Alternatively, pin `coincurve<21.0.0` if Python upgrade is not feasible.

affects: >=21.0.0

breakingCMake is a build dependency starting from `coincurve` version 20.0.0. While `pip` typically handles this for standard installations by fetching `cmake` from PyPI, redistributors or users building from source in custom environments will need to ensure CMake is available.

fix

Ensure CMake is installed and discoverable in your build environment. For standard `pip install`, no explicit action is usually required.

affects: >=20.0.0

breakingBinary wheels for Windows 32-bit are no longer built as of `coincurve` version 20.0.0. Users on Windows 32-bit systems will need to compile from source (which requires appropriate build tools and dependencies) or use an older version.

fix

Upgrade to a 64-bit Windows environment or pin `coincurve<20.0.0`.

affects: >=20.0.0

gotchaThe `PrivateKey.sign_recoverable()` method produces a 65-byte compact signature, which is NOT compatible with the module-level `coincurve.verify_signature()` function that expects a DER-encoded signature (produced by `PrivateKey.sign()`). Attempting to verify a recoverable signature with `verify_signature()` will raise a `ValueError`.

fix

Use `PrivateKey.sign()` when verifying with `coincurve.verify_signature()`. If you need recoverable signatures, verify them using `PublicKey.verify()` if applicable, or recover the public key first and then verify (more complex).

affects: All versions

gotchaA packaging issue in `coincurve==21.0.0` (specifically a missing LICENSE file in the `cffi` distribution during build) can lead to installation failures when `coincurve` is a dependency of another package. This was observed with `ccxt`.

fix

Pin your `coincurve` dependency to `coincurve==20.0.0` or `coincurve!=21.0.0` until a patched version is released. Or, consider updating to a newer working version if available.

affects: 21.0.0

Errors

Common errors & fixes

RuntimeError: Expected exactly one LICENSE file in cffi distribution, got 0.

This specific error occurs with `coincurve==21.0.0` due to a packaging bug where the build process expects a LICENSE file from the `cffi` distribution, but it is not found in the expected location during installation.

fix

Pin `coincurve` to an older, stable version like `20.0.0` using `pip install coincurve==20.0.0` to avoid the buggy version.

ERROR: Could not build wheels for coincurve, which is required to install pyproject.toml-based projects

`coincurve` relies on C extensions (specifically `libsecp256k1`) which require system-level development tools and libraries to be installed on your system to compile from source, especially if pre-built wheels are not available for your specific platform or Python version.

fix

Install the necessary system dependencies before running `pip install coincurve`. For Debian/Ubuntu, use `sudo apt-get install -y autoconf automake build-essential libffi-dev libtool pkg-config python3-dev`. For other operating systems, consult the `coincurve` documentation for equivalent packages.

ImportError: No module named 'coincurve'

This error typically indicates that the `coincurve` package was not installed correctly in the active Python environment, or the Python interpreter running the code cannot find the installed package. This can happen due to different Python environments (e.g., system Python vs. virtual environment) or an incomplete installation.

fix

Ensure `coincurve` is installed in your current Python environment by running `pip install coincurve`. If problems persist, verify you are using the correct Python interpreter or try reinstalling with `pip install --no-cache-dir coincurve` after ensuring all system build dependencies are met.

ModuleNotFoundError: No module named 'coincurve._libsecp256k1'

This error means that the `_libsecp256k1` C extension, which is a core component of `coincurve`, could not be found or loaded. This usually points to a failed or incomplete build of the `coincurve` package, often due to missing system-level dependencies during installation.

fix

This is often a symptom of the 'Could not build wheels' error. Ensure all necessary system build dependencies (like `build-essential`, `libffi-dev`, `python3-dev`) are installed on your system, then try reinstalling `coincurve` using `pip install coincurve --no-cache-dir --force-reinstall`.

TypeError: initializer for ctype 'secp256k1_ecdsa_recoverable_signature *' must be a cdata pointer, not bytes

This error occurs when you are attempting to pass a raw Python `bytes` object directly to a `coincurve` function that expects a CFFI `cdata` pointer type, particularly when working with operations like deserializing or converting signatures.

fix

Use `coincurve`'s dedicated serialization or deserialization functions to convert byte strings into the appropriate CFFI `cdata` types. For example, to handle recoverable signatures, use `coincurve.ecdsa.deserialize_recoverable(signature_bytes)` before passing it to other functions.

Upgrade

Version history

21.0.0latest on PyPI · released Mar 8, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

86 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ofek/coincurve ↗

packagehttps://pypi.org/project/coincurve/ ↗

homepagehttps://ofek.dev/coincurve/ ↗

changeloghttps://ofek.dev/coincurve/history/ ↗