TestNet Dispenser Client

The TestNet Dispenser Client is a utility for interacting with the AlgoKit TestNet Dispenser API. It provides methods to fund an account, register a refund for a transaction, and get the current limit for an account.

Creating a Dispenser Client

To create a Dispenser Client, you need to provide an authorization token. This can be done in two ways:

Pass the token directly to the client constructor as auth_token.
Set the token as an environment variable ALGOKIT_DISPENSER_ACCESS_TOKEN (see docs on how to obtain the token).

If both methods are used, the constructor argument takes precedence.

from algokit_utils import TestNetDispenserApiClient

# Using constructor argument

client = TestNetDispenserApiClient(auth_token="your_auth_token")

# Using environment variable

import os
os.environ["ALGOKIT_DISPENSER_ACCESS_TOKEN"] = "your_auth_token"
client = TestNetDispenserApiClient()

Funding an Account

To fund an account with Algos from the dispenser API, use the fund method. This method requires the receiver’s address, the amount to be funded, and the asset ID.

response = client.fund(address="receiver_address", amount=1000, asset_id=0)

The fund method returns a FundResponse object, which contains the transaction ID (tx_id) and the amount funded.

Registering a Refund

To register a refund for a transaction with the dispenser API, use the refund method. This method requires the transaction ID of the refund transaction.

client.refund(refund_txn_id="transaction_id")

Keep in mind, to perform a refund you need to perform a payment transaction yourself first by send funds back to TestNet Dispenser, then you can invoke this refund endpoint and pass the txn_id of your refund txn. You can obtain dispenser address by inspecting the sender field of any issued fund transaction initiated via fund.

Getting Current Limit

To get the current limit for an account with Algos from the dispenser API, use the get_limit method. This method requires the account address.

response = client.get_limit(address="account_address")

The get_limit method returns a LimitResponse object, which contains the current limit amount.

Error Handling

If an error occurs while making a request to the dispenser API, an exception will be raised with a message indicating the type of error. Refer to Error Handling docs for details on how you can handle each individual error code.