From 7e49964fc7862e3e6925f56850dbd018b61a70ef Mon Sep 17 00:00:00 2001
From: Shredder401k <triplejgotthatstrap@gmail.com>
Date: Sun, 28 Jun 2026 21:16:21 +0100
Subject: [PATCH] docs: add WebSocket ledger stream documentation and endpoint
 examples

---
 CHANGELOG.md | 25 +++++++++++++++++++
 README.md    | 69 ++++++++++++++++++++++++++++++++++++++++++++++------
 2 files changed, 86 insertions(+), 8 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 699229b..ec2a131 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+- Account age and longevity metrics endpoint: `GET /account/:id/age`
+- Asset freeze status check endpoint: `GET /account/:id/freeze-status/:assetCode/:assetIssuer`
+- Liquidity pool positions endpoint: `GET /account/:id/pool-positions`
+- Fee surge detection and recommendations endpoint: `GET /fee-estimate/surge-status`
+- Fee trends analysis endpoint: `GET /fee-estimate/trends`
+- DEX spread calculation endpoint: `GET /dex/spread/:sellAsset/:buyAsset`
+- DEX order book imbalance detection endpoint: `GET /dex/imbalance/:sellAsset/:buyAsset`
+- DEX arbitrage path discovery endpoint: `GET /dex/arbitrage/:assetCode/:assetIssuer`
+- Claimable balance evaluation endpoint: `GET /claimable-balances/:id/evaluate/:accountId`
+- Network ledger timing analysis endpoint: `GET /network/ledger-timing`
+- Liquidity pool profitability endpoint: `GET /liquidity-pools/:id/profitability`
+- Liquidity pool reserve ratio endpoint: `GET /liquidity-pools/:id/reserve-ratio`
+- Account counterparties analysis endpoint: `GET /account/:id/counterparties`
+- Transaction memo search endpoint: `GET /account/:id/transactions/search`
+- Account inactivity status endpoint: `GET /account/:id/inactivity`
+- Account subentry health endpoint: `GET /account/:id/subentry-health`
+- Account sponsorship relationships endpoint: `GET /account/:id/sponsorship`
+- Account can-receive asset check endpoint: `GET /account/:id/can-receive/:assetCode/:assetIssuer`
+- Account offer history endpoint: `GET /account/:id/offer-history`
+- Asset distribution and Gini coefficient endpoint: `GET /asset/:code/:issuer/distribution`
+- Network validators endpoint: `GET /network/validators`
+
 ## [1.0.0] - 2026-05-27
 
 ### Added
diff --git a/README.md b/README.md
index c946971..f889f21 100644
--- a/README.md
+++ b/README.md
@@ -1566,7 +1566,40 @@ GET /asset/search?code=USDC
 
 Establishes a live, real-time WebSocket connection to stream Stellar ledger updates. As new ledgers are closed on the Stellar blockchain, the API receives them via the Stellar Horizon SDK subscription, parses them, and immediately broadcasts them to connected WebSocket clients.
 
-#### Client Connection Example (Vanilla JS)
+#### Message Format
+
+Each ledger update is broadcast as a JSON object containing:
+
+```json
+{
+  "sequence": 51234567,
+  "closedAt": "2026-05-26T20:15:00Z",
+  "baseFee": 100,
+  "transactionCount": 54
+}
+```
+
+**Fields:**
+- `sequence` — The ledger sequence number (incremental counter)
+- `closedAt` — ISO 8601 timestamp when the ledger closed
+- `baseFee` — Base fee in stroops for transactions in this ledger
+- `transactionCount` — Number of successful transactions in this ledger
+
+#### CLI Example (wscat)
+
+Install wscat globally if you don't have it:
+```bash
+npm install -g wscat
+```
+
+Connect to the ledger stream:
+```bash
+wscat -c ws://localhost:3000/stream/ledgers
+```
+
+You'll immediately start receiving live ledger updates as they close on the network.
+
+#### Browser WebSocket API Example
 
 ```javascript
 const ws = new WebSocket("ws://localhost:3000/stream/ledgers");
@@ -1578,13 +1611,8 @@ ws.onopen = () => {
 ws.onmessage = (event) => {
   const ledger = JSON.parse(event.data);
   console.log("New ledger closed:", ledger);
-  // Example output:
-  // {
-  //   "sequence": 51234567,
-  //   "closedAt": "2026-05-26T20:15:00Z",
-  //   "baseFee": 100,
-  //   "transactionCount": 54
-  // }
+  console.log(`Ledger ${ledger.sequence} closed at ${ledger.closedAt}`);
+  console.log(`Transactions: ${ledger.transactionCount}, Base Fee: ${ledger.baseFee} stroops`);
 };
 
 ws.onerror = (error) => {
@@ -1596,6 +1624,31 @@ ws.onclose = () => {
 };
 ```
 
+#### Node.js Example
+
+```javascript
+const WebSocket = require("ws");
+
+const ws = new WebSocket("ws://localhost:3000/stream/ledgers");
+
+ws.on("open", () => {
+  console.log("Connected to StellarKit ledger stream!");
+});
+
+ws.on("message", (data) => {
+  const ledger = JSON.parse(data.toString());
+  console.log("New ledger:", ledger);
+});
+
+ws.on("error", (error) => {
+  console.error("WebSocket error:", error);
+});
+
+ws.on("close", () => {
+  console.log("Connection closed");
+});
+```
+
 ---
 
 ## Development