From 0fa45092b6c8dcf4049a091e292836acc632470b Mon Sep 17 00:00:00 2001
From: Denis Davidyuk <denis_davidyuk@hotmail.com>
Date: Wed, 24 Apr 2024 18:40:53 +1000
Subject: [PATCH] docs: JSON API

---
 README.md | 27 ++++++++++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 2a96a7f..ac57846 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,31 @@ If you navigate the user to the faucet from a wallet, it would be friendly to su
 https://faucet.aepps.com/?address=ak_21A27UVVt3hDkBE5J7rhhqnH5YNb4Y1dqo4PnSybrH85pnWo7E
 ```
 
+## JSON API
+
+Instead of using web UI, you can make a POST request to `https://faucet.aepps.com/account/<address>`. It will respond with a JSON containing transaction hash and an increased balance (in aettos)
+```json
+{
+  "tx_hash": "th_dxhmrcJY4bdqQrj5ZP1zBsuuKz4v4oyPNSqNS6TwTimPuJ3af",
+  "balance": "10000000000000000000"
+}
+```
+
+If you did top-up recently, you may get an error (425 code)
+```json
+{
+  "message": "The address ak_21A27UVVt3hDkBE5J7rhhqnH5YNb4Y1dqo4PnSybrH85pnWo7E is graylisted for another 2h 59m 24s"
+}
+```
+
+An example of requesting faucet using `fetch` API in JavaScript
+```js
+const address = 'ak_21A27UVVt3hDkBE5J7rhhqnH5YNb4Y1dqo4PnSybrH85pnWo7E';
+const url = `https://faucet.aepps.com/account/${address}`;
+const { status } = await fetch(url, { method: 'POST' });
+if (status !== 200) throw new Error(`Unexpected faucet response code: ${status}`);
+```
+
 ## Configuration
 
 Configuring Faucet application via environment variable:
@@ -40,4 +65,4 @@ make docker-run
 ```
 
 ### Notes:
-- The `frontend/index.html` is transformed into `index.mustache` in order to allow the node backend to provide dynamic values using the [Mustache](https://mustache.github.io/) template engine.
\ No newline at end of file
+- The `frontend/index.html` is transformed into `index.mustache` in order to allow the node backend to provide dynamic values using the [Mustache](https://mustache.github.io/) template engine.