Skip to main content

Aleo Python SDK (MainnetV0)

The Aleo Python SDK provides Python bindings to Aleo's zero-knowledge cryptographic primitives, built with snarkvm 4.12.0.

It ships two layers:

  • A Web3.py-style facade (aleo.Aleo / aleo.AsyncAleo) — a high-level, batteries-included client for connecting to a node, managing accounts, reading state, and building/proving/broadcasting transactions.
  • Low-level primitives (aleo.mainnet, aleo.testnet) — direct Python bindings to Aleo's cryptographic types, for when you need full control.

Quick Start (facade)

from aleo import Aleo

# Connect (construction is offline — no I/O until you make a call)
aleo = Aleo(Aleo.HTTPProvider("https://edge.provable.com/api"))
print(aleo.network_name)   # "mainnet"
print(aleo.network_id)     # 0

# Create an account (local)
account = aleo.account.create()
print(account.address)     # aleo1…

# Read a public balance  # requires a live node
balance = aleo.get_balance(str(account.address))
print(aleo.from_microcredits(balance), "credits")

Aleo.HTTPProvider is also importable directly as from aleo import HTTPProvider; the two are equivalent.

The verb ladder (sync)

The facade follows a clean top-to-bottom narrative: connect → account → read → build a call → inspect → send. Each rung does a little more than the one above it.

1. Connect

from aleo import Aleo

aleo = Aleo(Aleo.HTTPProvider("https://edge.provable.com/api"))

# Optional: check reachability  # requires a live node
if aleo.is_connected():
    print("connected to", aleo.network_name)

HTTPProvider is a config object, not a live connection — it is safe to construct without a network. It accepts network= ("mainnet" / "testnet"), api_key=, prover_uri= (the DPS endpoint), headers=, and a custom transport= callable.

2. Account — create or import (local)

# Fresh random account
account = aleo.account.create()

# Import from a private-key string (or a PrivateKey object)
account = aleo.account.from_private_key("APrivateKey1zkp…")

# Derive deterministically from a field seed
account = aleo.account.from_seed("123field")

# Sign / verify (bytes)
sig = aleo.account.sign(b"hello aleo", account)
assert aleo.account.verify(str(account.address), b"hello aleo", sig)

# Sign / verify a typed Aleo value
sv = aleo.account.sign_value("100u64", account)
assert aleo.account.verify_value(str(account.address), "100u64", sv)

Set aleo.default_account = account and the verbs below will use it whenever you omit the signer.

Note: the facade deliberately has no "recover signer from signature" verb. Aleo is a privacy chain — surfacing "which address signed this?" is a de-anonymisation vector. The low-level Signature.to_address() primitive remains available directly if you truly need it.

3. Read — balance and mappings

# Public credits balance in microcredits (0 if the address is unfunded)  # requires a live node
micro = aleo.get_balance(str(account.address))
print(aleo.from_microcredits(micro), "credits")

# Read any on-chain mapping through a bound Program  # requires a live node
credits = aleo.programs.get("credits.aleo")
raw = credits.mapping("account").get(str(account.address))
print("account mapping value:", raw)

Unit helpers are local: aleo.to_microcredits(1.5) == 1_500_000 and aleo.from_microcredits(1_500_000) == 1.5. Address validation is local too: aleo.is_valid_address(s) -> bool.

4. Build a call

aleo.programs.get(...) fetches a program and exposes its transitions as program.functions.<name>, mirroring web3.py's ABI-driven contract.functions. Calling one coerces your Python arguments to Aleo values and returns a BoundCall:

# requires a live node (to fetch the program source)
credits = aleo.programs.get("credits.aleo")

call = credits.functions.transfer_public(str(account.address), 1_000_000)
print(call.signature)   # "transfer_public(address, u64)"
print(call.args)        # ['aleo1…', '1000000u64']  — coerced

You can also list/iterate the available functions: list(credits.functions), "transfer_public" in credits.functions.

5. Inspect — simulate / .decoded()

Before proving or broadcasting anything, build the authorization locally and look at what the call will produce. This is a proof-free, network-free dry run:

auth = call.simulate(account)          # alias of .authorize(); .call() also works
print(auth.outputs)                    # per-transition output lists
print(auth.decoded())                  # [{program, function, inputs, outputs}, …]

Both AuthorizationResult and TransactionResult expose the same .outputs / .decoded() surface, plus a .raw escape hatch to the underlying network object. You can also decode after the fact with aleo.decode_transition(tx_id_or_transition).

6. Transact — full prove + broadcast

build_transaction (alias prove) runs the whole ladder locally: authorize → execute → prepare trace → prove execution → authorize+prove fee → assemble. transact does that and broadcasts, returning the transaction id:

# requires a live node + funded private key
tx_id = credits.functions.transfer_public(
    str(account.address), 100
).transact(account)

confirmed = aleo.network.wait_for_transaction(tx_id, timeout=60.0)

Fees are public by default (base cost from the execution). Pass priority_fee= for a tip, or opt into a private fee with private_fee=True (auto-sourced from aleo.record_provider) or by passing an explicit fee_record=.

7. Delegate — the flagship path (fee master pays by default)

delegate hands proving to a Delegated Proving Service (DPS): you build only the lightweight main authorization locally, and the DPS does the expensive SNARK proving. By default the prover's fee master pays the fee — no records, no public fee, no friction. That frictionlessness is the whole point.

# requires prover credentials; fee master pays
result = credits.functions.transfer_public(
    str(account.address), 100
).delegate(account)

Want to pay your own fee instead? delegate(account, pay_own_fee=True) (public) or delegate(account, fee_record=<credits record>) (private). Both bind the fee to the real execution id, so they prove the execution locally first. broadcast=False returns the proven transaction without submitting it.

Private transfers — delegated proving + record discovery

A full private transfer combines the two trust-minimising paths: delegated proving (the prover's fee master pays) and a record provider to discover the private records you own. The default record provider (aleo.records) uses Provable's hosted scanner — registering shares your view key with that service so it can index your records. If you'd rather not share a view key, assign your own RecordProvider instead.

# requires prover credentials + hosted-scanner registration
credits = aleo.programs.get("credits.aleo")

# 1) Move public credits into a private record (delegated — fee master pays)
credits.functions.transfer_public_to_private(str(account.address), 100_000) \
    .delegate(account)

# 2) Register with the record provider and find the new private record
aleo.records.register(account)                 # shares the view key with the scanner
record = aleo.records.get_unspent_credits_record()

# 3) Spend the private record with a private transfer (delegated)
credits.functions.transfer_private(record, str(recipient.address), 1) \
    .delegate(account)

aleo.record_provider is swappable: set it to your own object implementing the RecordProvider protocol (get_unspent_credits_record / find), and the whole facade (including private-fee auto-sourcing) uses it, with no view-key sharing.

Async (AsyncAleo)

The async facade mirrors the sync surface. Construction and the local, CPU-bound steps stay synchronous; everything that touches the network is awaitable.

import asyncio
from aleo import AsyncAleo

async def main():
    aleo = AsyncAleo(AsyncAleo.HTTPProvider("https://edge.provable.com/api"))
    print(aleo.network_name)   # sync — no I/O

    # Account ops are sync (purely local), even on AsyncAleo
    account = aleo.account.create()
    sig = aleo.account.sign(b"hi", account)
    assert aleo.account.verify(str(account.address), b"hi", sig)

    # Reads are awaited  # requires a live node
    micro = await aleo.get_balance(str(account.address))
    print(aleo.from_microcredits(micro), "credits")

    # Build a call — fetching the program is awaited  # requires a live node
    credits = await aleo.programs.get("credits.aleo")
    call = credits.functions.transfer_public(str(account.address), 100)

    # authorize / simulate / call are SYNC (local proof-free build)
    auth = call.simulate(account)
    print(auth.decoded())

    # transact / delegate are awaited  # requires a live node / prover creds
    tx_id = await call.transact(account)
    result = await call.delegate(account)   # fee master pays by default

asyncio.run(main())

Sync vs async on the async facade:

  • Sync (local, no I/O): account.* (create/import/sign/verify), to_microcredits / from_microcredits / is_valid_address, and authorize / simulate / call on a bound call.
  • Async (awaitable): is_connected, get_balance, programs.get, mapping reads, build_transaction / transact / delegate. Heavy proving runs in asyncio.to_thread so it does not block the event loop.

Testing utilities (aleo.testing)

The SDK ships an eth-tester-style harness for fast, deterministic local testing.

Devnode — a local chain in a context manager

Devnode launches a local aleo-devnode with manual block creation, so tests control exactly when blocks are produced. It auto-picks a free port and tears the node down on exit.

from aleo.testing import Devnode

with Devnode() as dn:
    aleo = dn.aleo                 # an Aleo client wired to the devnode
    alice = dn.accounts[0]         # 5 deterministic, pre-funded genesis accounts

    tx_id = aleo.programs.get("credits.aleo").functions.transfer_public(
        str(dn.accounts[1].address), 1_000_000
    ).transact(alice)

    dn.advance(1)                  # produce 1 block to confirm the tx
    snap = dn.snapshot()           # capture chain state
  • dn.aleo — an Aleo client pointed at the devnode.
  • dn.accounts — 5 deterministic, pre-funded genesis accounts.
  • dn.advance(n) — produce n blocks (the node runs with manual block creation).
  • dn.snapshot() — capture the current chain state.

Requires the aleo-devnode binary on your PATH, or set $ALEO_DEVNODE_BIN to its location.

Live end-to-end tests

The -m slow live tests hit a real testnet and skip automatically when their environment variables are unset:

Variable Purpose
ALEO_E2E_PRIVATE_KEY A funded testnet private key
ALEO_E2E_ENDPOINT Node/API endpoint to test against
ALEO_E2E_API_KEY Provable API key
ALEO_E2E_CONSUMER_ID DPS consumer id for delegated proving

The -m devnode tests additionally require the aleo-devnode binary (see Devnode above).

Low-level primitives

When you need direct control, import the network module and use the cryptographic types directly:

from aleo.mainnet import PrivateKey, Signature

# Generate a random private key
pk = PrivateKey.random()
address = pk.address
view_key = pk.view_key

# Sign a message
message = b"hello"
signature = Signature.sign(pk, message)
assert signature.verify(address, message)

aleo.mainnet (and aleo.testnet, when the extension is compiled) expose the full type set — Account, Program, Process, Authorization, Transaction, RecordPlaintext, Field, Address, and more.

Build & Install

bash install.sh

This creates a development environment and installs the aleo package with MainnetV0 bindings.

Contributing

If you wish to contribute, please follow the contribution guidelines outlined on GitHub.

Metadata

Release files for aleo-sdk 0.7.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aleo-sdk 0.7.0
File Size Uploaded Provenance Actions
aleo_sdk-0.7.0.tar.gz 357.4 kB With provenance Details for aleo_sdk-0.7.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for aleo-sdk 0.7.0
File Actions
aleo_sdk-0.7.0-cp37-abi3-win_amd64.whl CPython 3.7 abi3 Windows x86-64 Details for aleo_sdk-0.7.0-cp37-abi3-win_amd64.whl
aleo_sdk-0.7.0-cp37-abi3-manylinux_2_28_x86_64.whl CPython 3.7 abi3 Linux glibc 2.28+ x86-64 Details for aleo_sdk-0.7.0-cp37-abi3-manylinux_2_28_x86_64.whl
aleo_sdk-0.7.0-cp37-abi3-manylinux_2_28_aarch64.whl CPython 3.7 abi3 Linux glibc 2.28+ ARM64 Details for aleo_sdk-0.7.0-cp37-abi3-manylinux_2_28_aarch64.whl
aleo_sdk-0.7.0-cp37-abi3-macosx_11_0_arm64.whl CPython 3.7 abi3 macOS 11.0+ ARM64 Details for aleo_sdk-0.7.0-cp37-abi3-macosx_11_0_arm64.whl
aleo_sdk-0.7.0-cp37-abi3-macosx_10_12_x86_64.whl CPython 3.7 abi3 macOS 10.12+ x86-64 Details for aleo_sdk-0.7.0-cp37-abi3-macosx_10_12_x86_64.whl

Total release size: 181.7 MB

Release files / aleo_sdk-0.7.0.tar.gz

Download URL aleo_sdk-0.7.0.tar.gz
Size 357.4 kB
Tags Source
SHA-256 checksum
How to use checksums
c9250553020cd8744b715738156db99560f682a942e11fa50b3ff8e1cce1a89c
BLAKE2b-256 checksum
How to use checksums
ef16fb4782920930e9b2bdebb633c8ff142d5243ca662d9544b7367165b9546e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.

Transparency log

Release files / aleo_sdk-0.7.0-cp37-abi3-win_amd64.whl

Download URL aleo_sdk-0.7.0-cp37-abi3-win_amd64.whl
Size 34.6 MB
Tags CPython 3.7 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
3b95e509bc953d2e24c7029a98fc9c8e35a43eafe4bb22733f5b13e9735a04dd
BLAKE2b-256 checksum
How to use checksums
93db904c7e430472a18dd5098a3a21fe9e95d06eddecabf6e9f1e0cea9311317
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.

Transparency log

Release files / aleo_sdk-0.7.0-cp37-abi3-manylinux_2_28_x86_64.whl

Download URL aleo_sdk-0.7.0-cp37-abi3-manylinux_2_28_x86_64.whl
Size 37.2 MB
Tags CPython 3.7 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum
How to use checksums
2c1f7fb0243077c544d9be0b9d8dc1f5ba67c4df38e59479842dc33af45b2bbd
BLAKE2b-256 checksum
How to use checksums
d363a44481f0a010717aaf1aef2faae8518fb4b7810a8c1c1b8a7616ccaeb46e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.

Transparency log

Release files / aleo_sdk-0.7.0-cp37-abi3-manylinux_2_28_aarch64.whl

Download URL aleo_sdk-0.7.0-cp37-abi3-manylinux_2_28_aarch64.whl
Size 37.6 MB
Tags CPython 3.7 Linux glibc 2.28+ ARM64 abi3
SHA-256 checksum
How to use checksums
b2b977b87a28af229a9f4fbde3c87934a19bc264870d58b48a098e49d5c25ad1
BLAKE2b-256 checksum
How to use checksums
c25d494cbc8b390302079438d77a468ee033047ef65ea66e9b4eddfa15f7cfc6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.

Transparency log

Release files / aleo_sdk-0.7.0-cp37-abi3-macosx_11_0_arm64.whl

Download URL aleo_sdk-0.7.0-cp37-abi3-macosx_11_0_arm64.whl
Size 35.7 MB
Tags CPython 3.7 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
69bbf6601bbcf8dde9b7f763c59c118ad6a2ad716adc8bb9a3599b2d324964bb
BLAKE2b-256 checksum
How to use checksums
9128ec6ddd22361e1d968406cd48d92842643d6ed6cde56f169a870d4178df26
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.

Transparency log

Release files / aleo_sdk-0.7.0-cp37-abi3-macosx_10_12_x86_64.whl

Download URL aleo_sdk-0.7.0-cp37-abi3-macosx_10_12_x86_64.whl
Size 36.2 MB
Tags CPython 3.7 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
de51e80f2af4e5575a94cb964f5dce92ddd02205bd27b5cbe8ccaffb1d447e25
BLAKE2b-256 checksum
How to use checksums
3735ba94d12aa47f1e42a4d63ab6b286b27eac5d0f55e06cd653295cd5cfd789
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.

Transparency log

Security for aleo-sdk 0.7.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 6 files in this release have been uploaded with provenance metadata.

Select from 6 files

Attestation for aleo_sdk-0.7.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

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