Add docs and examples for sat recursive endpoint (#2735)

ordinals · Nov 24, 2023 · 7f5b3dd · 7f5b3dd
1 parent 59a8f6b
commit 7f5b3dd
Showing 1 changed file with 61 additions and 2 deletions.
diff --git 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"
+}
+```