AlgoKit TestNet Dispenser API Documentation

Overview

The AlgoKit TestNet Dispenser API provides functionalities to interact with the Dispenser service. This service enables users to fund and refund assets.

Base URLs

• Production Instance (publicly available): https://api.dispenser.algorandfoundation.tools

Authorization

All API endpoints require an Authorization header containing a valid JWT token.

Refer to algokit dispenser command documentation to learn how to obtain a valid JWT token by executing algokit dispenser login --ci command.

Endpoints

1. POST /fund/{assetID}

Funds a user's wallet with a specified asset.

URL Parameters:

Parameter	Description
assetID	ID of the asset for which the funding limit is sought. Use 0 for ALGO.

Request Body:

Parameter	Description
receiver	Address of the wallet to be funded.
amount	Amount of the asset to be funded.

Response Body:

{
    "txID": "string",
    "amount": "number"
}

Parameter	Description
txID	ID of the fund transaction from the dispenser to the requesting address.
amount	Amount of the asset to be funded.

2. GET /fund/{assetID}/limit

Fetches the funding limit for a specified asset.

URL Parameters:

Parameter	Description
assetID	ID of the asset for which the funding limit is sought. Use 0 for ALGO.

Response Body:

{
    "amount": "number"
}

Parameter	Description
amount	Current daily amount limit for the requested asset.

3. POST /refund

Allows refunding a transaction. A status code 200 indicates a successful refund.

Request Body:

{
    "refundTransactionID": "string"
}

Parameter	Description
refundTransactionID	ID of the refund transaction.

---

Error Handling

If an error occurs, the API returns a specific status and error code.

Error Codes Table:

Status Code	Error Code	Description
400	dispenser_out_of_funds	Dispenser is out of funds
403	forbidden	Dispenser access is forbidden
400	fund_limit_exceeded	Dispenser fund limit exceeded
400	missing_params	Missing required input parameters
403	authorization_error	Authorization error
400	txn_expired	Transaction expired
400	txn_invalid	Invalid transaction
400	txn_already_processed	Transaction already processed
404	txn_not_found	Transaction not found
400	invalid_asset	Unsupported asset ID
500	unexpected_error	Unexpected internal error

For more detailed error information, please refer to the error code in the response body.

Common Error Response

All error responses have the following common format:

{
    "code": "string",
    "message": "string"
}

Error Parameter	Description
code	Error code as described in the error codes table.
message	Error message.

missing_params error response

{
    "code": "missing_params",
    "message": "string",
    "parameters": ["string"]
}

Error Parameter	Description
parameters	List of missing parameters.

fund_limit_exceeded error response

{
    "code": "dispenser_fund_limit_exceeded",
    "message": "string",
    "limit": "number",
    "resetsAt": "string"
}

Error Parameter	Description
limit	Current daily amount limit for the requested asset.
resetsAt	Timestamp when the daily limit resets.