Skip to content

Wallets

AlgoPay manages Algorand accounts through AlgoPay.wallet, a WalletService backed by an in-memory WalletRepository unless you inject your own.

Keys and persistence

By default, private keys live in process memory only. For durable, encrypted storage and dashboard UX, use the hosted dashboard vault (pay/) with Control plane and POST /api/agent/pay, or implement a custom WalletRepository — see Documentation map for paths.

Wallet sets and wallets

Wallet sets group wallets (for example one set per agent or tenant). Each wallet has an id, Algorand address, and wallet_set_id.

client = AlgoPay(network=Network.ALGORAND_TESTNET)

ws = client.wallet.create_wallet_set("production-agent-1")
w = client.wallet.create_wallet(ws.id)

print(w.id, w.address, w.wallet_set_id)

You can also use convenience methods on AlgoPay that mirror this flow: create_wallet_set, create_wallet, list_wallets, get_wallet, etc. (see API reference).

USDC and opt-in

USDC on Algorand is an ASA. The account must opt in before it can hold USDC. Use:

client.wallet.opt_in_usdc(wallet_id, fee_level=FeeLevel.MEDIUM)

ASA ID comes from Config / network (mainnet vs testnet defaults) or ALGOPAY_USDC_ASA_ID.

Balances and transfers

  • get_usdc_balance_amount(wallet_id) — Decimal USDC balance (via Indexer).
  • Lower-level helpers on WalletService build and submit ASA transfers; high-level pay() on AlgoPay goes through the payment router (transfer vs x402).

Transaction history

client.wallet.list_transactions(wallet_id) returns TransactionInfo records tracked by the SDK/repository flow.

Fee levels

FeeLevel (LOW, MEDIUM, HIGH) maps to Algorand fee multipliers for sponsored transactions from the wallet service.