PyCardano

0.19.2 verified Fri May 01 auth: no python

A Python library for interacting with the Cardano blockchain. Supports transaction building, staking, native assets, smart contracts (Plutus), and integration with blockfrost, ogmios, and kupo. Current version: 0.19.2. Release cadence: roughly monthly.

pip install pycardano

Common errors

error from pycardano import PaymentSigningKey ImportError: cannot import name 'PaymentSigningKey' from 'pycardano' ↓

cause Using an older version (<0.12.0) where keys were in a submodule.

fix

Upgrade pycardano: pip install --upgrade pycardano

error pycardano.exception.InvalidTransactionException: Missing required signers ↓

cause The signing key was not passed or incorrectly passed to build_and_sign.

fix

Pass the signing key(s) as a list: tx_body, tx_hash = builder.build_and_sign([signing_key], change_address=address)

error AttributeError: module 'pycardano' has no attribute 'TransactionBuilder' ↓

cause Using a version before TransactionBuilder was added (pre-0.8.0) or incorrect import.

fix

Ensure pycardano >=0.8.0 and use: from pycardano import TransactionBuilder

Warnings

breaking In v0.19.0, the default CBOR library was changed to cbor2pure. If you rely on cbor2 C extension, set environment variable PYCA_CBOR2=1. ↓

fix export PYCA_CBOR2=1 or use cbor2 explicitly via pycardano configuration.

breaking From v0.16.0, version capping on dependencies was removed. This may cause incompatibility with older environments due to newer transitive dependencies. ↓

fix Pin dependencies in your project's requirements or test thoroughly when upgrading pycardano.

deprecated Support for Python 3.8 was dropped in v0.14.0. ↓

fix Upgrade to Python 3.9 or later.

gotcha TransactionBuilder's build_and_sign expects a list of signing keys, not a single key. Passing a single key will cause cryptic errors. ↓

fix Wrap your key in a list: [signing_key]

Imports

PaymentSigningKey

wrong

from pycardano.keys import PaymentSigningKey

correct

from pycardano import PaymentSigningKey

All key types were moved to pycardano top-level in v0.12.0.

TransactionBuilder

wrong

from pycardano.txbuilder import TransactionBuilder

correct

from pycardano import TransactionBuilder

Incorrect import path, TransactionBuilder is now at pycardano.

BlockFrostChainContext

wrong

from pycardano.blockfrost import BlockFrostChainContext

correct

from pycardano import BlockFrostChainContext

Chain contexts are top-level exports.

Quickstart

Generates a key pair, derives an address, and attempts to build a simple transaction using Blockfrost.

import os
from pycardano import (
    PaymentSigningKey,
    PaymentVerificationKey,
    Address,
    BlockFrostChainContext,
    TransactionBuilder,
    TransactionOutput,
    Value,
    Network
)

# Generate a key pair
signing_key = PaymentSigningKey.generate()
verification_key = PaymentVerificationKey.from_signing_key(signing_key)

# Derive address (testnet)
address = Address(payment_part=verification_key.hash(), network=Network.TESTNET)
print(f"Address: {address}")

# Create a chain context (use Blockfrost API key from env)
context = BlockFrostChainContext(
    base_url="https://cardano-testnet.blockfrost.io/api/v0",
    project_id=os.environ.get("BLOCKFROST_PROJECT_ID", "")
)

# Build a simple transaction (requires actual UTXOs and funds)
try:
    builder = TransactionBuilder(context)
    builder.add_output(TransactionOutput(address, Value(1000000)))
    tx_body, tx_hash = builder.build_and_sign([signing_key], change_address=address)
    print(f"Transaction hash: {tx_hash}")
except Exception as e:
    print(f"Error building transaction: {e}")