AlgoKit Utils API Reference | Algorand Developer Portal

AlgoKit Utils API Reference

A set of core Algorand utilities written in Python and released via PyPi that make it easier to build solutions on Algorand. This project is part of AlgoKit.

The goal of this library is to provide intuitive, productive utility functions that make it easier, quicker and safer to build applications on Algorand. Largely these functions wrap the underlying Algorand SDK, but provide a higher level interface with sensible defaults and capabilities for common tasks.

NOTE

If you prefer TypeScript there’s an equivalent TypeScript utility library.

Core principles

This library follows the Guiding Principles of AlgoKit and is designed with the following principles:

Modularity - This library is a thin wrapper of modular building blocks over the Algorand SDK; the primitives from the underlying Algorand SDK are exposed and used wherever possible so you can opt-in to which parts of this library you want to use without having to use an all or nothing approach.
Type-safety - This library provides strong type hints with effort put into creating types that provide good type safety and intellisense when used with tools like MyPy.
Productivity - This library is built to make solution developers highly productive; it has a number of mechanisms to make common code easier and terser to write.

Installation

This library can be installed from PyPi using pip or poetry:

pip install algokit-utils

# or

poetry add algokit-utils

Usage

The main entrypoint to the bulk of the functionality in AlgoKit Utils is the AlgorandClient class. You can get started by using one of the static initialization methods to create an Algorand client:

# Point to the network configured through environment variables or

# if no environment variables it will point to the default LocalNet configuration

algorand = AlgorandClient.from_environment()

# Point to default LocalNet configuration

algorand = AlgorandClient.default_localnet()

# Point to TestNet using AlgoNode free tier

algorand = AlgorandClient.testnet()

# Point to MainNet using AlgoNode free tier

algorand = AlgorandClient.mainnet()

# Point to a pre-created algod client

algorand = AlgorandClient.from_clients(algod=...)

# Point to a pre-created algod and indexer client

algorand = AlgorandClient.from_clients(algod=..., indexer=..., kmd=...)

# Point to custom configuration for algod

algod_config = AlgoClientNetworkConfig(server=..., token=..., port=...)

algorand = AlgorandClient.from_config(algod_config=algod_config)

# Point to custom configuration for algod and indexer and kmd

algod_config = AlgoClientNetworkConfig(server=..., token=..., port=...)

indexer_config = AlgoClientNetworkConfig(server=..., token=..., port=...)

kmd_config = AlgoClientNetworkConfig(server=..., token=..., port=...)

algorand = AlgorandClient.from_config(algod_config=algod_config, indexer_config=indexer_config, kmd_config=kmd_config)

Testing

AlgoKit Utils provides a dedicated documentation page on various useful snippets that can be reused for testing with tools like Pytest:

Testing

Types

The library leverages Python’s native type hints and is fully compatible with MyPy for static type checking.

All public abstractions and methods are organized in logical modules matching their domain functionality. You can import types either directly from the root module or from their source submodules. Refer to API documentation for more details.

Config and logging

To configure the AlgoKit Utils library you can make use of the Config object, which has a configure method that lets you configure some or all of the configuration options.

Config singleton

The AlgoKit Utils configuration singleton can be updated using config.configure(). Refer to the Config API documentation for more details.

Logging

AlgoKit has an in-built logging abstraction through the algokit_utils.config.AlgoKitLogger class that provides standardized logging capabilities. The logger is accessible through the config.logger property and provides various logging levels.

Each method supports optional suppression of output using the suppress_log parameter.

Debug mode

To turn on debug mode you can use the following:

from algokit_utils.config import config

config.configure(debug=True)

To retrieve the current debug state you can use debug property.

This will turn on things like automatic tracing, more verbose logging and advanced debugging. It’s likely this option will result in extra HTTP calls to algod and it’s worth being careful when it’s turned on.

Capabilities

The library helps you interact with and develop against the Algorand blockchain with a series of end-to-end capabilities as described below:

AlgorandClient - The key entrypoint to the AlgoKit Utils functionality
Core capabilities
- Client management - Creation of (auto-retry) algod, indexer and kmd clients against various networks resolved from environment or specified configuration, and creation of other API clients (e.g. TestNet Dispenser API and app clients)
- Account management - Creation, use, and management of accounts including mnemonic, rekeyed, multisig, transaction signer, idempotent KMD accounts and environment variable injected
- Algo amount handling - Reliable, explicit, and terse specification of microAlgo and Algo amounts and safe conversion between them
- Transaction management - Ability to construct, simulate and send transactions with consistent and highly configurable semantics, including configurable control of transaction notes, logging, fees, validity, signing, and sending behaviour
Higher-order use cases
- Asset management - Creation, transfer, destroying, opting in and out and managing Algorand Standard Assets
- Typed application clients - Type-safe application clients that are generated from ARC-56 or ARC-32 application spec files and allow you to intuitively and productively interact with a deployed app, which is the recommended way of interacting with apps and builds on top of the following capabilities:
  - ARC-56 / ARC-32 App client and App factory - Builds on top of the App management and App deployment capabilities (below) to provide a high productivity application client that works with ARC-56 and ARC-32 application spec defined smart contracts
  - App management - Creation, updating, deleting, calling (ABI and otherwise) smart contract apps and the metadata associated with them (including state and boxes)
  - App deployment - Idempotent (safely retryable) deployment of an app, including deploy-time immutability and permanence control and TEAL template substitution
- Algo transfers (payments) - Ability to easily initiate Algo transfers between accounts, including dispenser management and idempotent account funding
- Automated testing - Reusable snippets to leverage AlgoKit Utils abstractions in a manner that are useful for when writing tests in tools like Pytest.

Reference documentation

For detailed API documentation, see the algokit_utils