From 7f5b3ddd863fcdc97b04e7d9a255a6b59b9f427e Mon Sep 17 00:00:00 2001
From: raph <raphjaph@protonmail.com>
Date: Fri, 24 Nov 2023 21:32:40 +0100
Subject: [PATCH] Add docs and examples for sat recursive endpoint (#2735)

---
 docs/src/inscriptions/recursion.md | 63 +++++++++++++++++++++++++++++-
 1 file changed, 61 insertions(+), 2 deletions(-)

diff --git a/docs/src/inscriptions/recursion.md b/docs/src/inscriptions/recursion.md
index ce8ddbd09c..46d2ac6458 100644
--- a/docs/src/inscriptions/recursion.md
+++ b/docs/src/inscriptions/recursion.md
@@ -26,11 +26,70 @@ The recursive endpoints are:
 - `/r/blockhash`: latest block hash.
 - `/r/blockhash/<HEIGHT>`: block hash at given block height.
 - `/r/blocktime`: UNIX time stamp of latest block.
-- `/r/metadata/<INSCRIPTION_ID>`: returns a JSON string containing the hex-encoded CBOR metadata.
+- `/r/metadata/<INSCRIPTION_ID>`: JSON string containing the
+  hex-encoded CBOR metadata.
+- `/r/sat/<SAT_NUMBER>`: the first 100 inscription ids on a sat.
+- `/r/sat/<SAT_NUMBER>/<PAGE>`: the set of 100 inscription ids on `<PAGE>`.
+- `/r/sat/<SAT_NUMBER>/at/<INDEX>`: the inscription id at `<INDEX>` of all
+  inscriptions on a sat. `<INDEX>` may be a negative number to index from the
+  back. `0` being the first and `-1` being the most recent for example.
 
-Responses from the above recursive endpoints are JSON. For backwards compatibility additional endpoints are supported, some of which return plain-text responses.
+Note: `<SAT_NUMBER>` only allows the actual number of a sat no other sat
+notations like degree, percentile or decimal. We may expand to allow those in
+the future.
+
+Responses from the above recursive endpoints are JSON. For backwards
+compatibility additional endpoints are supported, some of which return
+plain-text responses.
 
 - `/blockheight`: latest block height.
 - `/blockhash`: latest block hash.
 - `/blockhash/<HEIGHT>`: block hash at given block height.
 - `/blocktime`: UNIX time stamp of latest block.
+
+Examples
+--------
+
+- `/r/blockheight`:
+
+```json
+777000
+```
+
+- `/r/blockhash/0`:
+
+```json
+"000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f"
+```
+
+- `/r/blocktime`:
+
+```json
+1700770905
+```
+
+- `/r/metadata/35b66389b44535861c44b2b18ed602997ee11db9a30d384ae89630c9fc6f011fi3`:
+
+```json
+"a2657469746c65664d656d6f727966617574686f726e79656c6c6f775f6f72645f626f74"
+```
+
+- `/r/sat/1023795949035695`:
+
+```json
+{
+   "ids":[
+      "17541f6adf6eb160d52bc6eb0a3546c7c1d2adfe607b1a3cddc72cc0619526adi0"
+   ],
+   "more":false,
+   "page":0
+}
+```
+
+- `/r/sat/1023795949035695/at/-1`:
+
+```json
+{
+   "id":"17541f6adf6eb160d52bc6eb0a3546c7c1d2adfe607b1a3cddc72cc0619526adi0"
+}
+```