# Algokit Utils Py

> Guide for writing Python code with AlgoKit Utils (`algokit-utils`). Use this skill whenever the user is building on Algorand with Python — client setup, account management, payments, ASA operations, atomic transaction groups, smart contract deployment and interaction (AppFactory, AppClient, ARC-56/ARC-32 specs), raw app calls, TEAL compilation, key registration, network management, error handling, and the low-level crypto primitives in `algokit_crypto` (Ed25519 keygen/signing/verification, Peikert xHD BIP44 wallets, wrapped-secret patterns) and `algokit_common` (`sha512_256`). Trigger on imports from `algokit_utils` or `algokit_crypto`, references to `AlgorandClient`, `AppFactory`, `AppClient`, `AlgoAmount`, `ed25519_generator`, `peikert_hd_wallet_generator`, `sha512_256`, `WrappedEd25519Seed`, or `RawEd25519Signer`, or any Python code that builds on Algorand.

- Skill: `algorand-devrel/algokit-utils-py` (Agent Skill, multi-file: 20 files)
- Install (CLI): `npx skillmds@latest add algorand-devrel/algokit-utils-py`
- Raw SKILL.md: https://api.skillmd.com/api/skills/algorand-devrel/algokit-utils-py/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: algorand-devrel (https://skillmd.com/u/algorand-devrel)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/algorand-devrel/algokit-utils-py

---


# AlgoKit Utils Python — Quick Reference

This skill targets **version 5.x** of `algokit-utils`.

This skill provides idiomatic patterns for `algokit-utils` (Python).
When helping users, prefer the patterns below over raw `algosdk` calls — AlgoKit Utils wraps the
SDK with higher-level, type-safe abstractions.

## How to use this skill

Reference docs are split into individual files under `references/`. Only read the file(s) relevant
to the user's question — this keeps context lean. The table below maps topics to filenames.

## Key concepts

- **AlgorandClient** is the single entry point. Create one via `AlgorandClient.default_localnet()`,
  `.testnet()`, `.mainnet()`, `.from_config()`, `.from_clients()`, or `.from_environment()`.
- **AlgoAmount** provides type-safe Algo/microAlgo values. Use `algo(5)`, `micro_algo(1000)`,
  `AlgoAmount.from_algo(5)`, or `AlgoAmount(algo=5)`.
- **AccountManager** (`algorand.account.*`) handles key generation, mnemonics, multisig, logic
  sigs, rekeyed accounts, funding, and signer registration.
- **TransactionComposer** (`algorand.new_group()`) builds atomic groups with fluent chaining.
  Supports `.add_payment()`, `.add_asset_transfer()`, `.add_app_call_method_call()`, etc.
- **AppFactory** creates and deploys smart contracts from ARC-56/ARC-32 app specs. Supports
  idempotent deploy with `on_update`/`on_schema_break` strategies and template variable substitution.
- **AppClient** interacts with deployed contracts — ABI method calls, state reads (global, local,
  box), bare calls, and the `params` builder for deferred composition.
- **Raw app calls** via `algorand.send.app_call()`, `.app_create()`, `.app_update()`,
  `.app_delete()`, `.app_call_method_call()`, `.app_create_method_call()` when you don't have an app spec.
- **TEAL compilation** via `algorand.app.compile_teal()` and `.compile_teal_template()` with
  caching and template variable substitution.
- **Crypto primitives** live in the standalone `algokit_crypto` package that ships alongside
  `algokit-utils`. This module carries Ed25519 keypair generation/signing/verification
  (`ed25519_generator`, `ed25519_verifier`), the Peikert xHD BIP44 wallet
  (`peikert_hd_wallet_generator`), and the wrapped-secret pattern for HSM/KMS-backed keys
  (`WrappedEd25519Seed`, `WrappedHdExtendedPrivateKey`,
  `ed25519_signing_key_from_wrapped_secret`). The Algorand SHA-512/256 primitive lives in
  `algokit_common` as `sha512_256`. Reach for these when you are building a custom
  `RawEd25519Signer`, deriving deterministic accounts from a seed, or computing
  Algorand-compatible hashes outside the transaction path.

## Key Python-specific differences from TypeScript

- Parameter objects use dataclasses (e.g., `PaymentParams`, `AssetCreateParams`) — pass them
  positionally to `algorand.send.*` methods.
- `AlgoAmount.algo` returns `Decimal` (not `number`); `.micro_algo` returns `int` (not `bigint`).
- `asset_opt_out()` takes `ensure_zero_balance` as a keyword argument outside the params object.
- `from_clients()` accepts pre-created SDK clients (`AlgodClient`, `IndexerClient`, `KmdClient`).
- Error types: `LogicError` (AVM failures), `TransactionComposerError` (group failures).
- Error transformers are sync functions `(Exception) -> Exception`, not async.

## Reference file index

Read only the file(s) relevant to the user's current question.

| File | What it covers |
|------|---------------|
| `references/getting-started.md` | Installation (`pip install algokit-utils`), imports, LocalNet prerequisites |
| `references/client-initialization.md` | LocalNet, TestNet, MainNet, custom config, from_clients, env vars |
| `references/account-management.md` | Random accounts, mnemonics, rekeyed, multisig, logic sigs, funding, signers |
| `references/algoamount-and-value-handling.md` | `algo()`, `micro_algo()`, conversions, transaction fees |
| `references/payment-transactions.md` | Simple payments, unsigned txns, notes, leases, fee control, close account |
| `references/asset-operations.md` | Create, opt-in/out, transfer, freeze, config, destroy, bulk ops, get info |
| `references/key-registration.md` | Online/offline key registration for consensus participation |
| `references/transaction-composition.md` | Atomic groups, multi-signer, atomic swaps, build/send/simulate, clone |
| `references/smart-contract-deployment.md` | AppFactory, bare/ABI create, idempotent deploy, template vars |
| `references/smart-contract-interaction.md` | AppClient, ABI calls, bare calls, global/local/box state, params builder |
| `references/raw-app-calls.md` | Low-level app create/call/update/delete, ABI method calls without app spec |
| `references/compile-teal.md` | compile_teal, compile_teal_template, template variable substitution |
| `references/network-and-client-management.md` | Algod/indexer/kmd access, LocalNet detection, validity window, params cache |
| `references/configuration-and-global-settings.md` | `populate_app_call_resources`, debug mode, trace collection, logging |
| `references/error-handling.md` | LogicError, parse_logic_error, TransactionComposerError, error transformers |
| `references/ed25519.md` | Ed25519 keypair generation, raw signers, signature verification, pinned PyNaCl backend |
| `references/hashing.md` | Algorand SHA-512/256 `sha512_256`, multisig and logic sig address construction |
| `references/hd-wallets.md` | `peikert_hd_wallet_generator`, BIP44 paths, multi-account derivation, wiring into `AccountManager` |
| `references/wrapped-secrets.md` | `WrappedEd25519Seed`, `WrappedHdExtendedPrivateKey`, `ed25519_signing_key_from_wrapped_secret`, HSM/KMS patterns |

## Common patterns to remember

- `algorand.send.*` builds, signs, and submits in one call.
- `algorand.create_transaction.*` builds without signing or sending.
- `app_client.params.*` builds call params for deferred use in groups.
- `app_client.send.bare.*` for bare calls; `app_client.send.call()` for ABI calls.
- Readonly ABI methods (marked in ARC-56) automatically use `simulate` — no fees spent.
- `algorand.account.ensure_funded()` is idempotent — skips if balance is already sufficient.
- `factory.deploy()` is idempotent — creates, updates, replaces, or no-ops based on state.
- Use `config.configure(populate_app_call_resources=True)` to auto-populate app call resources.
- `Method.from_signature("hello(string)string")` for raw ABI method calls without app spec.
- `generate_address_with_signers(ed25519_pubkey, raw_ed25519_signer)` from `algokit_transact`
  takes the pubkey and raw signer as separate positional args (plus an optional
  `sending_address` kwarg for rekeyed wiring) — unlike the TypeScript helper, it does not
  accept a single `Ed25519SigningKey` object. Pass its `.signer` to
  `algorand.account.set_signer(addr, signer)` — hardware wallets, KMS, and HD-derived keys all
  plug in through this one entry point.
- `ed25519_generator`, `ed25519_verifier`, and `ed25519_signing_key_from_wrapped_secret` are
  aliases that currently point at the PyNaCl-backed `pynacl_*` variants. Import the `pynacl_*`
  names directly when you need to pin the backend across future releases.
- `ed25519_signing_key_from_wrapped_secret` always zeroes the unwrapped `bytearray` after use
  and raises an `ExceptionGroup` (from the `exceptiongroup` backport) when both the operation
  and the re-wrap fail — never catch and discard it silently.
- The Peikert HD wallet seed size is **64 bytes** in Python (vs. 32 bytes in TypeScript).
- Python crypto is fully synchronous — `raw_ed25519_signer(bytes)` returns `bytes`, not a
  coroutine.