---
name: algokit-utils-py
description: >-
  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.
title: algokit-utils-py
canonical_url: https://skilld.dev/gh/algorandfoundation/algorand-agent-skills/algokit-utils-py
last_updated: 2026-09-28T19:01:11.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/account-management.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-py/references/account-management.md), [references/algoamount-and-value-handling.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-py/references/algoamount-and-value-handling.md), [references/asset-operations.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-py/references/asset-operations.md), [references/client-initialization.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-py/references/client-initialization.md), [references/compile-teal.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-py/references/compile-teal.md), [references/configuration-and-global-settings.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-py/references/configuration-and-global-settings.md), [references/ed25519.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-py/references/ed25519.md), [references/error-handling.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-py/references/error-handling.md), [references/getting-started.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-py/references/getting-started.md), [references/hashing.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-py/references/hashing.md), [references/hd-wallets.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-py/references/hd-wallets.md), [references/key-registration.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-py/references/key-registration.md), [references/network-and-client-management.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-py/references/network-and-client-management.md), [references/payment-transactions.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-py/references/payment-transactions.md), [references/raw-app-calls.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-py/references/raw-app-calls.md), [references/smart-contract-deployment.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-py/references/smart-contract-deployment.md), [references/smart-contract-interaction.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-py/references/smart-contract-interaction.md), [references/transaction-composition.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-py/references/transaction-composition.md), [references/wrapped-secrets.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-py/references/wrapped-secrets.md).
>
> If the user asked to install this Skill, run `npx skilld install algorandfoundation/algorand-agent-skills/algokit-utils-py`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/algokit-utils-py`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/algorandfoundation/algorand-agent-skills/algokit-utils-py) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/algokit-utils-py`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/algokit-utils-py --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/algokit-utils-py --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# 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.
