From a62011209205f2bd7ce25d13bed7ebdab3656d8d Mon Sep 17 00:00:00 2001
From: Akash Mondal <73akash58mondal@gmail.com>
Date: Fri, 19 Jun 2026 20:05:26 +0530
Subject: [PATCH] docs: add account utilities documentation

---
 README.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/README.md b/README.md
index 9f41eafc..2056bf21 100644
--- a/README.md
+++ b/README.md
@@ -338,6 +338,56 @@ const shareId = await agent.lp.getShareId();
   - **Classic best-route swaps (`agent.dex.*`):** Require `allowMainnet: true` in `AgentClient`
   - **Soroban single-pool swap/LP (`agent.swap()`, `agent.lp.*`):** Still wired to testnet-only contract settings
   - **Bridge operations:** Require BOTH `allowMainnet: true` AND `ALLOW_MAINNET_BRIDGE=true` in `.env`
+---
+
+## 🔍 Account Utilities
+
+AgentKit provides built-in tools for querying Stellar account balances and account details.
+
+### Get Account Balance
+
+```typescript
+import { stellarTools } from "stellartools";
+
+// Example input
+{
+  publicKey: "GBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
+  network: "testnet"
+}
+```
+
+Returns balances for XLM and all trustline assets associated with the account.
+
+### Get Account Information
+
+```typescript
+import { stellarTools } from "stellartools";
+
+// Example input
+{
+  publicKey: "GBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
+  network: "testnet"
+}
+```
+
+Returns account metadata including:
+
+* Sequence number
+* Thresholds
+* Signers
+* Account flags
+* Other Horizon account details
+
+### Supported Networks
+
+Both account utilities support:
+
+* `testnet`
+* `mainnet`
+
+The default network is `testnet`.
+
+
 
 ---