# 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](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/dispenser.md#login) 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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:
```json
{
"code": "string",
"message": "string"
}
```
| Error Parameter | Description |
| --------------- | ------------------------------------------------- |
| `code` | Error code as described in the error codes table. |
| `message` | Error message. |
### `missing_params` error response
```json
{
"code": "missing_params",
"message": "string",
"parameters": ["string"]
}
```
| Error Parameter | Description |
| --------------- | --------------------------- |
| `parameters` | List of missing parameters. |
### `fund_limit_exceeded` error response
```json
{
"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. |
