11 | 
12 | 
13 | 
14 | 
15 | 
16 |
17 |
21 |
22 | AlgoKit CLI is the one-stop shop tool for developers building on the [Algorand network](https://www.algorand.com/).
23 |
24 | AlgoKit gets developers of all levels up and running with a familiar, fun and productive development environment in minutes. The goal of AlgoKit is to help developers build and launch secure, automated production-ready applications rapidly.
25 |
26 | [Repo](https://github.com/algorandfoundation/algokit-cli) | [Quick Start Tutorial](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/tutorials/intro.md) | [Documentation](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/algokit.md)
27 |
28 | >[!NOTE]
29 | > By using the AlgoKit cli you will use all the below listed packages, no need to install them separately
30 |
31 | ### Algorand Python
32 | Algorand Python is a semantically and syntactically compatible, typed Python language that works with standard Python tooling and allows you to express smart contracts (apps) and smart signatures (logic signatures) for deployment on the Algorand Virtual Machine (AVM). [See how to get started](https://github.com/algorandfoundation/puya).
33 |
34 | ### AlgoKit Utils
35 | A set of core Algorand utilities available in both Python and TypeScript that make it easier to build solutions on Algorand.
36 |
37 | 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.
38 |
39 | ##### Python
40 | 
41 |
42 | [Repo](https://github.com/algorandfoundation/algokit-utils-py#readme) | [Documentation](https://algorandfoundation.github.io/algokit-utils-py/html/index.html)
43 |
44 |
45 | ##### TypeScript
46 | 
47 |
48 | [Repo](https://github.com/algorandfoundation/algokit-utils-ts#algokit-typescript-utilities) | [Documentation](https://github.com/algorandfoundation/algokit-utils-ts/tree/main/docs)
49 |
50 | ### Client Generators
51 | This project generates a type-safe smart contract client in both Python TypeScript for the Algorand Blockchain that wraps the [application client](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/docs/capabilities/app-client.md) in AlgoKit Utils. It does this by reading an [ARC-0032](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0032.md) application spec file.
52 |
53 | ##### Python
54 | 
55 |
56 | [Repo](https://github.com/algorandfoundation/algokit-client-generator-py) | [Examples](https://github.com/algorandfoundation/algokit-client-generator-py/tree/main/examples)
57 |
58 |
59 | ##### TypeScript
60 | 
61 |
62 | [Repo](https://github.com/algorandfoundation/algokit-client-generator-ts) | [Examples](https://github.com/algorandfoundation/algokit-client-generator-ts/tree/main/examples)
63 |
64 | ### AVM Debugger
65 | The AlgoKit AVM VS Code debugger extension provides a convenient way to debug any Algorand Smart Contracts written in TEAL
66 | [more info](https://marketplace.visualstudio.com/items?itemName=AlgorandFoundation.algokit-avm-vscode-debugger)
67 |
68 | ### TestNet Dispenser
69 | The AlgoKit TestNet Dispenser API provides functionalities to interact with the Dispenser service. This service enables users to fund and refund assets, testnet Algos only for now.
70 | [Documentation](./docs/testnet_api.md)
71 |
--------------------------------------------------------------------------------
/docs/testnet_api.md:
--------------------------------------------------------------------------------
1 | # AlgoKit TestNet Dispenser API Documentation
2 |
3 | ## Overview
4 |
5 | The AlgoKit TestNet Dispenser API provides functionalities to interact with the Dispenser service. This service enables users to fund and refund assets.
6 |
7 | ## Base URLs
8 |
9 | - **Production Instance (publicly available):**
10 | `https://api.dispenser.algorandfoundation.tools`
11 |
12 | ## Authorization
13 |
14 | All API endpoints require an `Authorization` header containing a valid JWT token.
15 |
16 | > 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.
17 |
18 | ## Endpoints
19 |
20 | ### 1. `POST /fund/{assetID}`
21 |
22 | Funds a user's wallet with a specified asset.
23 |
24 | **URL Parameters:**
25 |
26 | | Parameter | Description |
27 | | --------- | ------------------------------------------------------------------------ |
28 | | `assetID` | ID of the asset for which the funding limit is sought. Use `0` for ALGO. |
29 |
30 | **Request Body:**
31 |
32 | | Parameter | Description |
33 | | --------- | ----------------------------------- |
34 | | receiver | Address of the wallet to be funded. |
35 | | amount | Amount of the asset to be funded. |
36 |
37 | **Response Body:**
38 |
39 | ```json
40 | {
41 | "txID": "string",
42 | "amount": "number"
43 | }
44 | ```
45 |
46 | | Parameter | Description |
47 | | --------- | ------------------------------------------------------------------------ |
48 | | `txID` | ID of the fund transaction from the dispenser to the requesting address. |
49 | | `amount` | Amount of the asset to be funded. |
50 |
51 | ### 2. `GET /fund/{assetID}/limit`
52 |
53 | Fetches the funding limit for a specified asset.
54 |
55 | **URL Parameters:**
56 |
57 | | Parameter | Description |
58 | | --------- | ------------------------------------------------------------------------ |
59 | | `assetID` | ID of the asset for which the funding limit is sought. Use `0` for ALGO. |
60 |
61 | **Response Body:**
62 |
63 | ```json
64 | {
65 | "amount": "number"
66 | }
67 | ```
68 |
69 | | Parameter | Description |
70 | | --------- | --------------------------------------------------- |
71 | | `amount` | Current daily amount limit for the requested asset. |
72 |
73 | ### 3. `POST /refund`
74 |
75 | Allows refunding a transaction. A status code `200` indicates a successful refund.
76 |
77 | **Request Body:**
78 |
79 | ```json
80 | {
81 | "refundTransactionID": "string"
82 | }
83 | ```
84 |
85 | | Parameter | Description |
86 | | ------------------- | ----------------------------- |
87 | | refundTransactionID | ID of the refund transaction. |
88 |
89 | ---
90 |
91 | ## Error Handling
92 |
93 | If an error occurs, the API returns a specific status and error code.
94 |
95 | **Error Codes Table:**
96 |
97 | | Status Code | Error Code | Description |
98 | | ----------- | ------------------------ | --------------------------------- |
99 | | 400 | `dispenser_out_of_funds` | Dispenser is out of funds |
100 | | 403 | `forbidden` | Dispenser access is forbidden |
101 | | 400 | `fund_limit_exceeded` | Dispenser fund limit exceeded |
102 | | 400 | `missing_params` | Missing required input parameters |
103 | | 403 | `authorization_error` | Authorization error |
104 | | 400 | `txn_expired` | Transaction expired |
105 | | 400 | `txn_invalid` | Invalid transaction |
106 | | 400 | `txn_already_processed` | Transaction already processed |
107 | | 404 | `txn_not_found` | Transaction not found |
108 | | 400 | `invalid_asset` | Unsupported asset ID |
109 | | 500 | `unexpected_error` | Unexpected internal error |
110 |
111 | For more detailed error information, please refer to the error code in the response body.
112 |
113 | ## Common Error Response
114 |
115 | All error responses have the following common format:
116 |
117 | ```json
118 | {
119 | "code": "string",
120 | "message": "string"
121 | }
122 | ```
123 |
124 | | Error Parameter | Description |
125 | | --------------- | ------------------------------------------------- |
126 | | `code` | Error code as described in the error codes table. |
127 | | `message` | Error message. |
128 |
129 | ### `missing_params` error response
130 |
131 | ```json
132 | {
133 | "code": "missing_params",
134 | "message": "string",
135 | "parameters": ["string"]
136 | }
137 | ```
138 |
139 | | Error Parameter | Description |
140 | | --------------- | --------------------------- |
141 | | `parameters` | List of missing parameters. |
142 |
143 | ### `fund_limit_exceeded` error response
144 |
145 | ```json
146 | {
147 | "code": "dispenser_fund_limit_exceeded",
148 | "message": "string",
149 | "limit": "number",
150 | "resetsAt": "string"
151 | }
152 | ```
153 |
154 | | Error Parameter | Description |
155 | | --------------- | --------------------------------------------------- |
156 | | `limit` | Current daily amount limit for the requested asset. |
157 | | `resetsAt` | Timestamp when the daily limit resets. |
158 |
--------------------------------------------------------------------------------