---
name: algokit-utils-ts
description: >-
  Guide for writing TypeScript code with AlgoKit Utils (`@algorandfoundation/algokit-utils`). Use this skill whenever the user is building on Algorand with TypeScript — client setup, account management, payments, asset operations, atomic transaction groups, smart contract deployment and interaction (AppFactory, AppClient, ARC-56/ARC-32 specs), raw app calls, key registration, network management, testing with algorandFixture, error handling, and the low-level crypto primitives under `@algorandfoundation/algokit-utils/crypto` (Ed25519 keygen/signing/verification, SHA-512/256 `hash`, Peikert xHD BIP44 wallets, wrapped-secret patterns). Trigger on imports from `@algorandfoundation/algokit-utils` (incl. `/crypto`, `/testing`, `/transact` subpaths), references to `AlgorandClient`, `AppFactory`, `AppClient`, `AlgoAmount`, `algorandFixture`, `ed25519Generator`, `peikertXHdWalletGenerator`, `hash`, `WrappedEd25519Seed`, or `RawEd25519Signer`. Also on any TypeScript or JavaScript code that builds on Algorand.
title: algokit-utils-ts
canonical_url: https://skilld.dev/gh/algorandfoundation/algorand-agent-skills/algokit-utils-ts
last_updated: 2026-09-29T08:23:58.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-ts/references/account-management.md), [references/algoamount-and-value-handling.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-ts/references/algoamount-and-value-handling.md), [references/asset-operations.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-ts/references/asset-operations.md), [references/client-initialization.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-ts/references/client-initialization.md), [references/configuration-and-global-settings.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-ts/references/configuration-and-global-settings.md), [references/ed25519.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-ts/references/ed25519.md), [references/error-handling.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-ts/references/error-handling.md), [references/getting-started.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-ts/references/getting-started.md), [references/hashing.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-ts/references/hashing.md), [references/hd-wallets.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-ts/references/hd-wallets.md), [references/key-registration.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-ts/references/key-registration.md), [references/network-and-client-management.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-ts/references/network-and-client-management.md), [references/payment-transactions.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-ts/references/payment-transactions.md), [references/raw-app-calls.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-ts/references/raw-app-calls.md), [references/smart-contract-deployment.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-ts/references/smart-contract-deployment.md), [references/smart-contract-interaction.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-ts/references/smart-contract-interaction.md), [references/testing-utilities.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-ts/references/testing-utilities.md), [references/transaction-composition.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-ts/references/transaction-composition.md), [references/wrapped-secrets.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algokit-utils-ts/references/wrapped-secrets.md).
>
> If the user asked to install this Skill, run `npx skilld install algorandfoundation/algorand-agent-skills/algokit-utils-ts`. 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-ts`, 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-ts) 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-ts`. 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-ts --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/algokit-utils-ts --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 TypeScript — Quick Reference

This skill targets **version 10.x** of `@algorandfoundation/algokit-utils`.

This skill provides idiomatic patterns for `@algorandfoundation/algokit-utils` (TypeScript).
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.defaultLocalNet()`,
  `.testNet()`, `.mainNet()`, `.fromConfig()`, or `.fromEnvironment()`.
- **AlgoAmount** provides type-safe Algo/microAlgo values. Use `algo(5)`, `microAlgo(1000)`,
  `AlgoAmount.Algo(5)`, or the prototype extensions `(5).algo()`.
- **AccountManager** (`algorand.account.*`) handles key generation, mnemonics, multisig, logic
  sigs, funding, and signer registration.
- **TransactionComposer** (`algorand.newGroup()`) builds atomic groups with fluent chaining.
  Supports `.addPayment()`, `.addAssetTransfer()`, `.addAppCallMethodCall()`, etc.
- **AppFactory** creates and deploys smart contracts from ARC-56/ARC-32 app specs. Supports
  idempotent deploy with `onUpdate`/`onSchemaBreak` 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.appCall()`, `.appCreate()`, `.appUpdate()`, `.appDelete()`,
  `.appCallMethodCall()`, `.appCreateMethodCall()` when you don't have an app spec.
- **Crypto primitives** are exposed via `@algorandfoundation/algokit-utils/crypto`
  (re-exporting `@algorandfoundation/algokit-crypto`). This subpath carries Ed25519
  keypair generation/signing/verification (`ed25519Generator`, `ed25519Verifier`),
  Algorand's SHA-512/256 `hash`, the Peikert xHD BIP44 wallet
  (`peikertXHdWalletGenerator`), and the wrapped-secret pattern for HSM/KMS-backed
  keys (`WrappedEd25519Seed`, `WrappedHdExtendedPrivateKey`,
  `ed25519SigningKeyFromWrappedSecret`). Reach for it when you are building a custom
  `RawEd25519Signer`, deriving deterministic accounts from a seed, or computing
  Algorand-compatible hashes outside the transaction path.

## Reference file index

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

| File | What it covers |
|------|---------------|
| `references/getting-started.md` | Installation, imports, LocalNet prerequisites |
| `references/client-initialization.md` | LocalNet, TestNet, MainNet, custom config, env vars |
| `references/account-management.md` | Random accounts, mnemonics, multisig, logic sigs, funding, signers |
| `references/algoamount-and-value-handling.md` | `algo()`, `microAlgo()`, conversions, prototype extensions, fees |
| `references/payment-transactions.md` | Simple payments, unsigned txns, notes, leases, fee control |
| `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, build/send/simulate, fee control, 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/network-and-client-management.md` | Algod/indexer/kmd access, LocalNet detection, rounds, timestamps, time/block warp |
| `references/configuration-and-global-settings.md` | `populateAppCallResources`, confirmation rounds, logging |
| `references/testing-utilities.md` | `algorandFixture`, `newScope`, `generateAccount`, transaction logger, log capture, indexer waits |
| `references/error-handling.md` | Try/catch patterns, error transformers, overspend, app call rejections |
| `references/ed25519.md` | Ed25519 keypair generation, raw signers, signature verification, pinned Noble backend |
| `references/hashing.md` | Algorand SHA-512/256 `hash`, multisig and logic sig address construction |
| `references/hd-wallets.md` | `peikertXHdWalletGenerator`, BIP44 paths, multi-account derivation, wiring into `AccountManager` |
| `references/wrapped-secrets.md` | `WrappedEd25519Seed`, `WrappedHdExtendedPrivateKey`, `ed25519SigningKeyFromWrappedSecret`, HSM/KMS patterns |

## Common patterns to remember

- `algorand.send.*` builds, signs, and submits in one call.
- `algorand.createTransaction.*` builds without signing or sending.
- `appClient.params.*` builds call params for deferred use in groups or nested args.
- `appClient.send.bare.*` for bare calls; `appClient.send.call()` for ABI calls.
- Readonly ABI methods (marked in ARC-56) automatically use `simulate` — no fees spent.
- `algorand.account.ensureFunded()` is idempotent — skips if balance is already sufficient.
- `factory.deploy()` is idempotent — creates, updates, replaces, or no-ops based on state.
- Use `Config.configure({ populateAppCallResources: true })` to auto-populate app call resources.
- `generateAddressWithSigners` from `@algorandfoundation/algokit-utils/transact`
  accepts anything shaped like `{ ed25519Pubkey, rawEd25519Signer }` (i.e.
  `Ed25519SigningKey`) and returns an `AddressWithSigners`. Pass its `.signer` to
  `AccountManager.setSigner(addr, signer)` — hardware wallets, KMS, and HD-derived
  keys all plug in through this single shape.
- `ed25519Generator`, `ed25519Verifier`, and `ed25519SigningKeyFromWrappedSecret` are
  aliases that currently point at the `@noble/ed25519`-backed `noble*` variants. Import
  the `noble*` names directly when you need to pin the backend across future releases.
- `ed25519SigningKeyFromWrappedSecret` always zeroes the unwrapped secret after use and
  throws an `AggregateError` when both the operation and the re-wrap fail — never catch
  and discard it silently.
