API reference · ZecPy docs

Amounts are integers in zatoshis (1 ZEC = 100,000,000). Methods marked local send nothing to the server. Everything that touches the network is async.

The privacy flags on paying methods default to off, and both refusals raise PrivacyError:

allow_transparent=False: pay a transparent-only recipient.
allow_pool_crossing=False: move value between shielded pools in public.

Wallet

Wallet.create

Python

await Wallet.create(path, *, network, server, tor=True, regtest_heights=None)
    -> tuple[Wallet, Mnemonic]

Creates a wallet directory with a fresh 24-word seed. network is "main", "test" or "regtest". The mnemonic is returned once and stored nowhere. Raises FileExistsError if a wallet already exists at path.

Wallet.restore

Python

await Wallet.restore(path, mnemonic, *, network, server, birthday=None, tor=True,
                     regtest_heights=None) -> Wallet

Recreates a wallet from its mnemonic. Without birthday it scans the whole chain.

Wallet.watch

Python

await Wallet.watch(path, bundle, *, server, birthday=None, tor=True,
                   regtest_heights=None) -> Wallet

A watch-only wallet from a WatchBundle or its JSON. It syncs, reports balances, issues invoices and builds unsigned transactions, but cannot spend.

Wallet.open

Python

Wallet.open(path, *, server, mnemonic=None, tor=True) -> Wallet

Opens an existing wallet directory. Without the mnemonic it is watch-only. A mnemonic that does not belong to the wallet raises PrivacyError.

Properties

Name	Type	Meaning
`path`	`Path`	The wallet directory
`network`	`str`	`"main"`, `"test"` or `"regtest"`
`can_send`	`bool`	False for watch-only wallets
`invoices`	`Invoices`	The invoice book, stored in `invoices.db`

Chain and state

Method	Returns	Notes
`await sync()`	`int`	Scans to the tip; returns the synced height
`balance()`	`Balance`	Local
`address()`	`str`	Local; a fresh Unified Address with shielded receivers only
`transactions(since=0)`	`list[Transaction]`	Local; newest first
`transaction(txid)`	`Transaction` or `None`	Local
`await fetch_memos(*, decoys=7, max_delay=10.0)`	`MemoReport`	Opt-in; Tor; see Memos

Paying

Method	Returns	Notes
`await send(to, amount_zat, memo=None, *, flags, max_broadcast_delay=0.0)`	txid
`await send_many(payments, *, flags, max_broadcast_delay=0.0)`	txid	Up to 50 `Payout`s or tuples
`propose(to, amount_zat, memo=None, *, flags)`	`Proposal`	Local
`propose_many(payments, *, flags)`	`Proposal`	Local
`propose_sweep(to, memo=None, *, mode="spendable", flags)`	`Proposal`	Local; `mode` is `"spendable"` or `"everything"`
`await send_proposal(proposal, *, max_broadcast_delay=0.0)`	txid	Sends exactly that proposal
`parse_request(uri)`	`PaymentRequest`	Local; ZIP-321
`await pay(uri, *, max_zat, flags, max_broadcast_delay=0.0)`	txid	`max_zat` is required

Cold signing

Method	Returns	Notes
`propose_cold(to, amount_zat, memo=None, *, flags)`	`bytes`	An unsigned, proved PCZT
`propose_cold_many(payments, *, flags)`	`bytes`	Up to 50 recipients
`await broadcast_signed(signed_pczt, *, max_broadcast_delay=0.0)`	txid	On its own Tor circuit

Invoices

Method	Returns	Notes
`create(amount_zat, reference)`	`Invoice`	A fresh shielded address; `reference` unique
`get(invoice_id)`	`Invoice`	`KeyError` if missing
`by_reference(reference)`	`Invoice`	`KeyError` if missing
`status(invoice)`	`InvoiceStatus`
`paid_zat(invoice)`	`int`	Confirmed value received
`poll(confirmations=3)`	`list[PaymentEvent]`	Call after `sync()`
`async watch(confirmations=3, poll_interval=10.0)`	async iterator of `PaymentEvent`	Syncs in a loop

Data types

Invoice: id, reference, amount_zat, address, created_at, and uri, a ZIP-321 URI.

PaymentEvent: state ("detected", "confirmed" or "reverted"), invoice, txid, pool, value_zat, height, confirmations, invoice_paid_zat, and invoice_settled.

InvoiceStatus: invoice, state ("unpaid", "pending", "partial" or "paid"), confirmed_zat, pending_zat.

Balance: total, spendable, pending, sapling, orchard, ironwood, chain_tip, scanned_height.

Transaction: txid, status, mined_height, confirmations, block_time, expiry_height, net_value, fee, pool_crossing_value, memo_count, memo_pending, outputs.

TxOutput: pool, output_index, direction, value, address, diversifier_index, memo, memo_bytes. The repr hides memo contents.

Proposal: fee, paying_out, payments, spends, change, crossing_value, canonical_crossing, target_height.

PaymentRequest: payments as (address, amount_zat, label, message, has_memo) tuples, and total.

MemoReport: fetched, waiting, unavailable.

Payout: Payout(address, amount_zat, memo=None), a frozen dataclass.

Mnemonic: prints as Mnemonic(<24 words, hidden>); reveal() returns the phrase.

ColdSigner

Python

ColdSigner(mnemonic, *, network, account=0, regtest_heights=None)
ColdSigner.generate(*, network, account=0, regtest_heights=None) -> (ColdSigner, Mnemonic)

Method	Returns	Notes
`watch_bundle()`	`WatchBundle`	For `Wallet.watch`
`inspect(pczt)`	`Summary`	Spending, outputs with change found by key, fee
`sign(pczt)`	`bytes`	Refuses a PCZT that spends nothing of this signer's

WatchBundle: network, ufvk, seed_fingerprint, account; to_json() and WatchBundle.from_json(text). It cannot spend but reveals the account's history.

Errors

See Errors.