Pre-release

This release is a pre-release and may not be stable for production use.

Cardano Client Bindings — Python

Python bindings for Cardano Client Lib via the Cardano Client Bindings native library. Pure ctypes — no JVM, no compiler, no C extension.

Part of the Cardano Client Bindings project. See the top-level README for the full API reference and docs/quicktx.md for transaction building.

Requirements

  • Python 3.8+

The native library is bundled inside the platform wheel — no separate download or CCL_LIB_PATH needed for an installed package.

Installing

Recommended — a platform wheel that bundles the native library:

pip install cardano-client-lib
# or, a locally built wheel:
pip install path/to/cardano_client_lib-*.whl

Wheels are published for linux-x86_64, linux-aarch64, linux-musl-x86_64 (Alpine), macos-aarch64, and windows-x86_64. There is no source distribution — on any other platform, build libccl from source and point CCL_LIB_PATH at it (see below).

The distribution is named cardano-client-lib, but the import stays short: import ccl. The wheel ships the matching libccl.* inside the package (ccl/_libs/), so import ccl just works — nothing else to set. Build one locally (needs pip install build):

./gradlew :wrappers:python:wheel     # -> wrappers/python/dist/cardano_client_lib-*.whl

At load time the bindings look for the library in this order: an explicit CclLib(lib_path=...), the CCL_LIB_PATH env var, then the bundled ccl/_libs/ copy.

Development — against a locally built library (no wheel): point CCL_LIB_PATH at a directory containing libccl.{dylib,so,dll}:

./gradlew :core:nativeCompile        # produces core/build/native/nativeCompile/libccl.*
export CCL_LIB_PATH=core/build/native/nativeCompile
# (or: make download-lib to fetch a pre-built binary)

Running the examples

The package finds the library via the CCL_LIB_PATH environment variable, and the OS loader needs it on its search path too. From the repo root:

LIB_DIR=core/build/native/nativeCompile

PYTHONPATH=wrappers/python \
CCL_LIB_PATH=$LIB_DIR \
DYLD_LIBRARY_PATH=$LIB_DIR \
LD_LIBRARY_PATH=$LIB_DIR \
  python3 wrappers/python/examples/01_account_and_keys.py

(DYLD_LIBRARY_PATH is for macOS, LD_LIBRARY_PATH for Linux — set both, the unused one is harmless.)

The examples/ directory contains:

File What it shows
01_account_and_keys.py Create an account, restore from mnemonic, derive keys and a DRep ID
02_primitives.py Mnemonics, Blake2b hashing, Ed25519 signing, address parsing/validation
03_build_and_sign_tx.py Build an unsigned payment offline (QuickTx) and sign it — no node/DevKit needed

Quick start

from ccl import CclLib, Network

lib = CclLib()                      # loads libccl, starts a GraalVM isolate
try:
    account = lib.account.create(Network.TESTNET)
    print(account["base_address"])  # addr_test1...
    print(account["mnemonic"])      # 24-word phrase
finally:
    lib.close()                     # tears down the isolate

API namespaces

A CclLib instance exposes these namespaces (all offline operations):

Namespace Examples
lib.account create, from_mnemonic, get_private_key, get_public_key, get_drep_id, sign_tx
lib.address info, validate, to_bytes, from_bytes
lib.crypto blake2b_256, blake2b_224, generate_mnemonic, validate_mnemonic, sign, verify
lib.tx hash, sign_with_secret_key, to_json, from_json, deserialize
lib.plutus data_hash, data_to_json, data_from_json
lib.script native_from_json, hash
lib.gov drep_key_from_mnemonic, committee_cold_key_from_mnemonic, committee_hot_key_from_mnemonic
lib.wallet create, from_mnemonic, get_address
lib.quicktx build(yaml, utxos, protocol_params) — build an unsigned tx from a TxPlan YAML document

Networks

Every key-derivation and signing call takes a required network — Network.MAINNET, Network.TESTNET, Network.PREPROD or Network.PREVIEW. There is no default: a library that derives keys must not guess, least of all guess mainnet.

Network is CCL's enum ordinal, not Cardano's on-chain network id. The two differ, and for mainnet/testnet they are inverted:

Member Value you pass On-chain network_id of the address
Network.MAINNET 0 1
Network.TESTNET 1 0
Network.PREPROD 2 0
Network.PREVIEW 3 0

So do not pass a network_id you read off an address back into these APIs — you would flip mainnet and testnet. lib.address.info(addr)["network_id"] is the real on-chain id and is a different thing from the Network you passed in.

Network is an IntEnum, so a plain int 0-3 still works, and an out-of-range value raises ValueError at the call rather than failing obscurely inside the native library.

Errors raise ccl.CclError.

Transactions are defined as a TxPlan YAML document and built fully offline — you supply the UTXOs and protocol parameters:

result = lib.quicktx.build(txplan_yaml, utxos, protocol_params)  # -> {"tx_cbor","tx_hash","fee"}

See examples/03_build_and_sign_tx.py.

Chain-data providers (optional)

build() is offline — you supply the UTXOs and protocol parameters. The optional providers fetch those for you over HTTP (stdlib urllib), so the native library stays offline and provider-free:

from ccl import CclLib, YaciProvider, BlockfrostProvider

lib = CclLib()
provider = BlockfrostProvider(project_id, network="preprod")  # or YaciProvider()
result = lib.quicktx.build_with(txplan_yaml, provider, sender_address)

Plug in any backend (Koios, Ogmios, …) by supplying an object with utxos(address) and protocol_params(). UTXO selection is handled inside the bridge — a provider only returns all UTXOs at the address.

Transaction evaluators (optional)

A Plutus build needs each redeemer's execution units. The bridge computes them offline with Scalus when you supply none — so a script build just works, no evaluation step:

result = lib.quicktx.build_with(txplan_yaml, provider, sender_address)  # Scalus computes the units

To use a remote evaluator instead (e.g. an authoritative fallback), pass a TransactionEvaluator; build_with runs a two-pass (draft → evaluate → rebuild). libccl never makes HTTP calls (ADR-0013), so remote evaluation lives here in the wrapper:

from ccl import BlockfrostEvaluator

evaluator = BlockfrostEvaluator(project_id, network="preprod")
result = lib.quicktx.build_with(txplan_yaml, provider, sender_address, evaluator=evaluator)

Plug in any evaluator (Ogmios, …) by supplying an object with evaluate(tx_cbor, utxos). To supply units you computed yourself, call build(..., exec_units=…) directly. See examples/04_plutus_evaluator.py.

Project links

Data verified by PyPI on Aug 26, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for satran004 from gravatar.com satran004

Credits

Author: bloxbean

GitHub Statistics

Data verified by PyPI on Aug 26, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.8

Tags

cardano cardano-client cardano-client-lib blockchain

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

cardano_client_lib-0.1.0rc6-py3-none-win_amd64.whl (26.4 MB view details)

Uploaded Python 3Windows x86-64

cardano_client_lib-0.1.0rc6-py3-none-musllinux_1_2_x86_64.whl (26.4 MB view details)

Uploaded Python 3musllinux: musl 1.2+ x86-64

cardano_client_lib-0.1.0rc6-py3-none-manylinux_2_28_x86_64.whl (26.4 MB view details)

Uploaded Python 3manylinux: glibc 2.28+ x86-64

cardano_client_lib-0.1.0rc6-py3-none-manylinux_2_28_aarch64.whl (26.4 MB view details)

Uploaded Python 3manylinux: glibc 2.28+ ARM64

cardano_client_lib-0.1.0rc6-py3-none-macosx_15_0_arm64.whl (26.4 MB view details)

Uploaded Python 3macOS 15.0+ ARM64

File details

Details for the file cardano_client_lib-0.1.0rc6-py3-none-win_amd64.whl.

File metadata

File hashes

Hashes for cardano_client_lib-0.1.0rc6-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 e0dd3bc3d8d8fcf276f0eeeda645817719f78d67820566dcf4b64cf4dba9899e
MD5 04cd1ce2530e06aa031253007627e5ef
BLAKE2b-256 cbdd024997336f95c0f2b27df7beab3b40b5e7aa020e0d812c437227a663313b

See more details on using hashes here.

Provenance

The following attestation bundles were made for cardano_client_lib-0.1.0rc6-py3-none-win_amd64.whl:

Publisher: publish-py.yml on bloxbean/cardano-client-bindings

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file cardano_client_lib-0.1.0rc6-py3-none-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for cardano_client_lib-0.1.0rc6-py3-none-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 cee5e18763587925100429f737dffe5ce76db020b4c7b0174afbf29fcb33a777
MD5 524a9412828ffee71d77a81b4810b393
BLAKE2b-256 d8fe8917e5623ef85708cf129812a892e9535acada31fbce3d45f88671e46ef3

See more details on using hashes here.

Provenance

The following attestation bundles were made for cardano_client_lib-0.1.0rc6-py3-none-musllinux_1_2_x86_64.whl:

Publisher: publish-py.yml on bloxbean/cardano-client-bindings

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file cardano_client_lib-0.1.0rc6-py3-none-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for cardano_client_lib-0.1.0rc6-py3-none-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 f6abd175bbc4275374d299a2740bb8c8ae88670ddb00426babc351bd92f1370f
MD5 9e3644db2bc7b391037c3e51a25a4907
BLAKE2b-256 346a324543ac1859bda2471f0327a215169eb68bf0b9008c828455e08d3d2ac6

See more details on using hashes here.

Provenance

The following attestation bundles were made for cardano_client_lib-0.1.0rc6-py3-none-manylinux_2_28_x86_64.whl:

Publisher: publish-py.yml on bloxbean/cardano-client-bindings

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file cardano_client_lib-0.1.0rc6-py3-none-manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for cardano_client_lib-0.1.0rc6-py3-none-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 61694cc4777345d2a05cd5d735884514d4a2f926ac135de2f651356c64e9d604
MD5 538bb945d3ff77cec3cd270a780cde82
BLAKE2b-256 8260efffdbe148d531f03e573db406a0300c0e9d670d6ed1a53464426c7d0fcc

See more details on using hashes here.

Provenance

The following attestation bundles were made for cardano_client_lib-0.1.0rc6-py3-none-manylinux_2_28_aarch64.whl:

Publisher: publish-py.yml on bloxbean/cardano-client-bindings

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file cardano_client_lib-0.1.0rc6-py3-none-macosx_15_0_arm64.whl.

File metadata

File hashes

Hashes for cardano_client_lib-0.1.0rc6-py3-none-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 a7ed43a6a80103dc000f4eaa89140a7d2544f8d2978b5fadef5647f6911fd194
MD5 97f1cf81da7c376942f493c6f2d7571e
BLAKE2b-256 ddb35639a503537530e00597638d3fce73361a33c6478e3a3454da8171f5f918

See more details on using hashes here.

Provenance

The following attestation bundles were made for cardano_client_lib-0.1.0rc6-py3-none-macosx_15_0_arm64.whl:

Publisher: publish-py.yml on bloxbean/cardano-client-bindings

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release
Pre-release

0.1.0rc6 This release

5 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page