@zuhaibnoor/zigchain-sdk 1.0.3 → 1.1.1

package/docs/bank.md

@@ -1,7 +1,59 @@
-## Bank Module
+# Bank Module
 
-The **Bank module** allows you to query token balances, token supply, and metadata of denominations on the ZigChain network.
-It is mainly used to inspect account balances and understand what tokens exist on the chain.
+## What is the Bank Module?
+
+The **Bank module** is a core Cosmos SDK module responsible for managing **token balances and transfers** on the blockchain.
+
+In **ZigChain**, every token you hold — whether the native `uzig` or any factory-created token — is tracked and queryable through this module.
+
+---
+
+## Important Terminology
+
+### Denom
+
+A **denom** (denomination) is the unique identifier for a token on ZigChain.
+
+Examples:
+```
+uzig
+coin.zig1zpnw5dtzzttmgtdjgtywt08wnlyyskpuupy3cfw8mytlslx54j9sgz6w4n.oroswap
+```
+
+There are two categories of denoms on ZigChain:
+
+| Type | Example | Description |
+| ---- | ------- | ----------- |
+| Native | `uzig` | The base chain token |
+| Factory token | `coin.<creator-address>.<name>` | Tokens created via the token factory module |
+
+---
+
+### uzig
+
+The base denomination of ZigChain's native token.
+
+`1 ZIG = 1,000,000 uzig`
+
+Most balance queries return amounts in `uzig`.
+
+---
+
+### Balance
+
+The amount of a specific denom held by an address.
+
+---
+
+### Total Supply
+
+The total circulating amount of a denom across all accounts on the chain.
+
+---
+
+### Pagination
+
+Many bank queries return paginated responses when results are large (e.g. total supply across 1800+ denoms). The `pagination` object in the response contains a `next_key` for fetching subsequent pages.
 
 ---
 
@@ -13,303 +65,910 @@ import {
   getNetworkEndpoints,
   Network,
 } from '@zuhaibnoor/zigchain-sdk'
-```
 
-```ts
 const endpoints = getNetworkEndpoints(Network.Testnet)
 const bankApi = new ChainBankApi(endpoints)
+
+const address = 'zig1svkn4sqrlz8r6krq96ty6kze54n2ec03u0vat5'
 ```
 
 ---
 
-## `fetchBalance`
+# 1️⃣ fetchBalances
 
-Query the balance of a **specific token denom** for an account.
+## Method
+
+```ts
+async fetchBalances(address: string)
+```
 
-**CLI equivalent**
+## CLI Equivalent
 
 ```bash
-zigchaind query bank balance <address> <denom>
+zigchaind query bank balances <address>
 ```
 
-**Method**
+## Description
 
-```ts
-fetchBalance(address: string, denom: string)
-```
+Fetches **all token balances** held by an account across every denom.
+
+This returns every denom the address holds — both native tokens and factory-created tokens.
+
+## Parameters
+
+| Name    | Type   | Description                       |
+| ------- | ------ | --------------------------------- |
+| address | string | Bech32 address of the account to query |
 
-**Example**
+
+## Usage Example
 
 ```ts
-const balance = await bankApi.fetchBalance(
-  'zig1svkn4sqrlz8r6krq96ty6kze54n2ec03u0vat5',
-  'uzig'
-)
+const balances = await bankApi.fetchBalances(address)
+console.dir(balances, { depth: null })
+```
 
-console.log(balance)
+## Example Response
+
+```json
+{
+  "balances": [
+    {
+      "denom": "coin.zig1zpnw5dtzzttmgtdjgtywt08wnlyyskpuupy3cfw8mytlslx54j9sgz6w4n.oroswap",
+      "amount": "222026"
+    },
+    {
+      "denom": "uzig",
+      "amount": "443143284"
+    }
+  ],
+  "pagination": {
+    "next_key": null,
+    "total": "2"
+  }
+}
 ```
 
+## Response Field Explanation
+
+### `balances`
+
+Array of token balances held by the account.
+
+Each entry contains:
+
+| Field  | Description                                |
+| ------ | ------------------------------------------ |
+| denom  | Token identifier (native or factory token) |
+| amount | Token amount as a string integer           |
+
+## When to Use
+
+* Displaying a wallet's full token portfolio
+* Checking if an address holds a particular token
+* Building wallet dashboards or block explorer account pages
+
 ---
 
-## `fetchBalances`
+# 2️⃣ fetchBalance
 
-Query **all token balances** owned by an account.
+## Method
 
-**CLI equivalent**
+```ts
+async fetchBalance(address: string, denom: string)
+```
+
+## CLI Equivalent
 
 ```bash
-zigchaind query bank balances <address>
+zigchaind query bank balance <address> <denom>
 ```
 
-**Method**
+## Description
 
-```ts
-fetchBalances(address: string)
-```
+Fetches the balance of a **single specific denom** for an account.
+
+Use this when you only need to check one token rather than fetching all balances with `fetchBalances`. This is more efficient for targeted lookups.
+
+## Parameters
 
-**Example**
+| Name    | Type   | Description                                   |
+| ------- | ------ | --------------------------------------------- |
+| address | string | Bech32 address of the account to query        |
+| denom   | string | Token identifier to query the balance of      |
+
+## Usage Example
 
 ```ts
-const balances = await bankApi.fetchBalances(
-  'zig1svkn4sqrlz8r6krq96ty6kze54n2ec03u0vat5'
-)
+const balance = await bankApi.fetchBalance(address, 'uzig')
+console.dir(balance, { depth: null })
+```
 
-console.log(balances)
+## Example Response
+
+```json
+{
+  "balance": {
+    "denom": "uzig",
+    "amount": "443143284"
+  }
+}
 ```
 
+## Response Field Explanation
+
+### `balance`
+
+| Field  | Description                           |
+| ------ | ------------------------------------- |
+| denom  | The queried token denomination        |
+| amount | Token amount held, as a string integer |
+
+> ⚠️ If the account holds none of the queried denom, `amount` will be `"0"` rather than an error.
+
+### `fetchBalance` vs `fetchBalances`
+
+| Feature               | fetchBalance               | fetchBalances              |
+| --------------------- | -------------------------- | -------------------------- |
+| Targets specific denom | ✅ Yes                    | ❌ Returns all denoms      |
+| Response size         | Minimal                    | Larger (all tokens)        |
+| Use case              | Single token lookup        | Full portfolio view        |
+
+## When to Use
+
+* Checking if an account has enough of a specific token before a transaction
+* Displaying a single token balance in a UI
+* Gas or fee balance checks
+* Targeted balance monitoring
+
 ---
 
-## `fetchTotalSupply`
+# 3️⃣ fetchTotalSupply
+
+## Method
 
-Query the **total supply of all tokens** on the chain.
+```ts
+async fetchTotalSupply()
+```
 
-**CLI equivalent**
+## CLI Equivalent
 
 ```bash
 zigchaind query bank total-supply
 ```
 
-**Method**
+## Description
 
-```ts
-fetchTotalSupply()
-```
+Fetches the **total circulating supply of every token** registered on the chain.
 
-**Example**
+This returns a paginated list of all denoms and their total supply across all accounts. On ZigChain testnet, this spans 1800+ denoms including the native token and all factory-created tokens.
+
+## Parameters
+
+None.
+
+## Usage Example
 
 ```ts
 const supply = await bankApi.fetchTotalSupply()
-console.log(supply)
+console.dir(supply, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "supply": [
+    {
+      "denom": "abc",
+      "amount": "200000000000000000000"
+    },
+    {
+      "denom": "coin.zig108xf844zaf34609lugw69z5urkrutxlu78jfrr09v2d7wqqhptzsz97tk7.night",
+      "amount": "14853334"
+    },
+    {
+      "denom": "uzig",
+      "amount": "9827461000000"
+    }
+  ],
+  "pagination": {
+    "next_key": "Y29pbi56aWcxMHh2YzN0a3FyZHl5bTZlcDlscnQ1MDA1bXJ3dnc2cm1sNjZxdjdqeHduemxwcWZtdzdrc3E3bjdubS5wb3dlcg==",
+    "total": "1829"
+  }
+}
 ```
 
+## Response Field Explanation
+
+### `supply`
+
+Array of all token denominations and their total supply.
+
+Each entry contains:
+
+| Field  | Description                                                  |
+| ------ | ------------------------------------------------------------ |
+| denom  | Token identifier                                             |
+| amount | Total supply of this token across all accounts, as a string  |
+
+### `pagination`
+
+| Field    | Description                                                                     |
+| -------- | ------------------------------------------------------------------------------- |
+| next_key | Base64-encoded cursor for the next page. `null` when all results are returned   |
+| total    | Total number of distinct denoms registered on the chain                          |
+
+> ⚠️ ZigChain testnet has 1800+ registered denoms. The response is paginated — `next_key` will be non-null if there are more results beyond the current page.
+
+## When to Use
+
+* Chain analytics and supply dashboards
+* Verifying a token exists on-chain before interacting with it
+* Monitoring total supply changes over time
+* Building block explorer overview pages
+
 ---
 
-## `fetchSupplyOf`
+# 4️⃣ fetchSupplyOf
+
+## Method
 
-Query the **total supply of a specific token denom**.
+```ts
+async fetchSupplyOf(denom: string)
+```
 
-**CLI equivalent**
+## CLI Equivalent
 
 ```bash
 zigchaind query bank total-supply-of <denom>
 ```
 
-**Method**
+## Description
 
-```ts
-fetchSupplyOf(denom: string)
-```
+Fetches the **total circulating supply of a single specific denom**.
+
+This is the targeted alternative to `fetchTotalSupply` — use this when you only need the supply of one token rather than pulling the entire paginated list of all 1800+ denoms.
+
+## Parameters
 
-**Example**
+| Name  | Type   | Description                              |
+| ----- | ------ | ---------------------------------------- |
+| denom | string | Token identifier to query the supply of  |
+
+## Usage Example
 
 ```ts
 const supplyOf = await bankApi.fetchSupplyOf('uzig')
-console.log(supplyOf)
+console.dir(supplyOf, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "amount": {
+    "denom": "uzig",
+    "amount": "2323139530948522"
+  }
+}
 ```
 
+## Response Field Explanation
+
+### `amount`
+
+| Field  | Description                                                 |
+| ------ | ----------------------------------------------------------- |
+| denom  | The queried token denomination                              |
+| amount | Total supply of this token across all accounts, as a string |
+
+### `fetchSupplyOf` vs `fetchTotalSupply`
+
+| Feature                 | fetchSupplyOf         | fetchTotalSupply           |
+| ----------------------- | --------------------- | -------------------------- |
+| Targets specific denom  | ✅ Yes                | ❌ Returns all denoms      |
+| Response size           | Minimal               | Large (paginated)          |
+| Use case                | Single token supply   | Full chain supply overview |
+
+## When to Use
+
+* Checking the total supply of a specific token
+* Supply monitoring for a particular denom
+* Token analytics dashboards
+
 ---
 
-## `fetchDenomMetadata`
+# 5️⃣ fetchDenomMetadata
+
+## Method
 
-Query metadata information for a specific token denom (name, symbol, decimals, etc.).
+```ts
+async fetchDenomMetadata(denom: string)
+```
 
-**CLI equivalent**
+## CLI Equivalent
 
 ```bash
 zigchaind query bank denom-metadata <denom>
 ```
 
-**Method**
+## Description
 
-```ts
-fetchDenomMetadata(denom: string)
-```
+Fetches the **registered metadata** for a specific token denomination.
 
-**Example**
+Metadata describes how a token is represented to humans — its name, symbol, display unit, and the full hierarchy of denominations at different exponents. 
+
+## Parameters
+
+| Name  | Type   | Description                                   |
+| ----- | ------ | --------------------------------------------- |
+| denom | string | Base denomination to query metadata for (e.g. `uzig`) |
+
+
+## Usage Example
 
 ```ts
 const metadata = await bankApi.fetchDenomMetadata('uzig')
-console.log(metadata)
+console.dir(metadata, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "metadata": {
+    "description": "ZIGChain Test Native Token",
+    "denom_units": [
+      { "denom": "uzig", "exponent": 0, "aliases": ["microzig"] },
+      { "denom": "mzig", "exponent": 3, "aliases": ["millizig"] },
+      { "denom": "zig",  "exponent": 6, "aliases": [] }
+    ],
+    "base": "uzig",
+    "display": "zig",
+    "name": "ZIG",
+    "symbol": "ZIG",
+    "uri": "",
+    "uri_hash": ""
+  }
+}
 ```
 
+## Response Field Explanation
+
+### `metadata`
+
+| Field       | Description                                                             |
+| ----------- | ----------------------------------------------------------------------- |
+| description | Human-readable description of the token                                 |
+| denom_units | Array of denomination representations at different decimal exponents    |
+| base        | The smallest, indivisible unit of the token (used in all on-chain math) |
+| display     | The recommended unit to show in UIs                                     |
+| name        | Full token name                                                         |
+| symbol      | Short ticker symbol                                                     |
+| uri         | Optional URI pointing to additional token metadata (e.g. logo)          |
+| uri_hash    | Hash of the URI content for integrity verification                      |
+
+### `denom_units`
+
+Defines the denomination hierarchy. Each entry represents the same token at a different decimal scale.
+
+| Field    | Description                                            |
+| -------- | ------------------------------------------------------ |
+| denom    | Name of this unit                                      |
+| exponent | Power of 10 relative to the base denom                 |
+| aliases  | Alternative names for this unit                        |
+
+For `uzig` specifically:
+
+| Unit  | Exponent | Meaning                          |
+| ----- | -------- | -------------------------------- |
+| uzig  | 0        | Base unit — 1 uzig               |
+| mzig  | 3        | 1 mzig = 1,000 uzig              |
+| zig   | 6        | 1 zig = 1,000,000 uzig (display) |
+
+> Always use the `base` denom for on-chain operations and the `display` denom for showing amounts to end users.
+
+## When to Use
+
+* Displaying token amounts in human-readable form
+* Getting the token symbol and name for a UI
+* Resolving decimal precision for amount formatting
+* Token info pages on block explorers
+
 ---
 
-## `fetchDenomOwners`
+# 6️⃣ fetchDenomOwners
+
+## Method
 
-Query **all accounts that hold a specific token denom**.
+```ts
+async fetchDenomOwners(denom: string)
+```
 
-**CLI equivalent**
+## CLI Equivalent
 
 ```bash
 zigchaind query bank denom-owners <denom>
 ```
 
-**Method**
+## Description
 
-```ts
-fetchDenomOwners(denom: string)
-```
+Fetches **all accounts that hold a non-zero balance** of a specific denom, along with the amount each holds.
 
-**Example**
+This is a full holder list query. For widely held tokens like `uzig`, this can return a very large paginated dataset — `uzig` has over 129,000 holders on testnet.
+
+## Parameters
+
+| Name  | Type   | Description                                      |
+| ----- | ------ | ------------------------------------------------ |
+| denom | string | Token identifier to query the holder list for    |
+
+## Usage Example
 
 ```ts
 const owners = await bankApi.fetchDenomOwners('uzig')
-console.log(owners)
+console.dir(owners, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "denom_owners": [
+    {
+      "address": "zig1qqqxk89xs2hnm59cuwdej6f4r8l9552nth4tj4",
+      "balance": { "denom": "uzig", "amount": "99255569" }
+    },
+    {
+      "address": "zig1qqqk3yl9dgfh88mg2hlcanjh2easyu6u6lk2m5",
+      "balance": { "denom": "uzig", "amount": "199106024" }
+    }
+  ],
+  "pagination": {
+    "next_key": "FAAs0VsyF6XXIzu1kVs/+aGFecf2",
+    "total": "129756"
+  }
+}
 ```
 
+## Response Field Explanation
+
+### `denom_owners`
+
+Array of all accounts holding this token.
+
+Each entry contains:
+
+| Field           | Description                                  |
+| --------------- | -------------------------------------------- |
+| address         | Bech32 address of the token holder           |
+| balance.denom   | The queried denomination                     |
+| balance.amount  | Amount held by this address, as a string     |
+
+### `pagination`
+
+| Field    | Description                                                                      |
+| -------- | -------------------------------------------------------------------------------- |
+| next_key | Base64-encoded cursor for the next page. `null` when all results are returned    |
+| total    | Total number of accounts holding this denom                                      |
+
+> ⚠️ For native tokens like `uzig`, this list can exceed 100,000 entries. Always check `pagination.next_key` and handle multi-page responses if you need the complete dataset.
+
+## When to Use
+
+* Building token holder leaderboards
+* Analytics on token distribution and concentration
+* Checking whether a specific address holds a given token
+
 ---
 
-## `fetchAllDenomsMetadata`
+# 7️⃣ fetchAllDenomsMetadata
+
+## Method
 
-Query metadata for **all registered token denominations** on the chain.
+```ts
+async fetchAllDenomsMetadata()
+```
 
-**CLI equivalent**
+## CLI Equivalent
 
 ```bash
 zigchaind query bank denoms-metadata
 ```
 
-**Method**
+## Description
 
-```ts
-fetchAllDenomsMetadata()
-```
+Fetches **metadata for all registered token denominations** on the chain in a single paginated response.
+
+This is the bulk version of `fetchDenomMetadata` — instead of querying one denom at a time, this returns metadata for every denom that has registered metadata on-chain. On ZigChain testnet, this spans nearly 3,000 entries including native tokens and factory-created tokens.
+
+> ⚠️ Not every denom has registered metadata. Denoms without metadata will not appear in this response.
 
-**Example**
+## Parameters
+
+None.
+
+## Usage Example
 
 ```ts
 const allMetadata = await bankApi.fetchAllDenomsMetadata()
-console.log(allMetadata)
-```
+console.dir(allMetadata, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "metadatas": [
+    {
+      "description": "ZIGChain Test Native Token",
+      "denom_units": [
+        { "denom": "uzig", "exponent": 0, "aliases": ["microzig"] },
+        { "denom": "zig",  "exponent": 6, "aliases": [] }
+      ],
+      "base": "uzig",
+      "display": "zig",
+      "name": "ZIG",
+      "symbol": "ZIG",
+      "uri": "",
+      "uri_hash": ""
+    },
+    {
+      "description": "Cool denom: coin.zig10xvc3tkqrdyym6ep9lrt5005mrwvw6rml66qv7jxwnzlpqfmw7ksq7n7nm.callumdi",
+      "denom_units": [
+        {
+          "denom": "coin.zig10xvc3tkqrdyym6ep9lrt5005mrwvw6rml66qv7jxwnzlpqfmw7ksq7n7nm.callumdi",
+          "exponent": 0,
+          "aliases": []
+        },
+        { "denom": "callumdi", "exponent": 6, "aliases": [] }
+      ],
+      "base": "coin.zig10xvc3tkqrdyym6ep9lrt5005mrwvw6rml66qv7jxwnzlpqfmw7ksq7n7nm.callumdi",
+      "display": "coin.zig10xvc3tkqrdyym6ep9lrt5005mrwvw6rml66qv7jxwnzlpqfmw7ksq7n7nm.callumdi",
+      "name": "callumdi",
+      "symbol": "modiad",
+      "uri": "https://memesfun.mypinata.cloud/ipfs/bafkreifb4n6bkfvrh25rl6rpvoq7yva5b4xjut3tqidjyxishhgyi67ohi",
+      "uri_hash": "2943831a20722913d07baf10952816d85671b1f773120005cc0063056ff980bd"
+    }
+  ],
+  "pagination": {
+    "next_key": "Y29pbi56aWcxMHh2YzN0a3FyZHl5bTZlcDlscnQ1MDA1bXJ3dnc2cm1sNjZxdjdqeHduemxwcWZtdzdrc3E3bjdubS5jaGVja2luZ2Jp",
+    "total": "2963"
+  }
+}
+```
+
+## Response Field Explanation
+
+### `metadatas`
+
+Array of metadata entries for all registered denoms. Each entry has the same structure as the response from `fetchDenomMetadata`.
+
+| Field       | Description                                                          |
+| ----------- | -------------------------------------------------------------------- |
+| description | Human-readable description of the token                              |
+| denom_units | Denomination hierarchy at different decimal exponents                |
+| base        | Smallest indivisible unit — used for all on-chain operations         |
+| display     | Recommended unit to show in UIs                                      |
+| name        | Full token name                                                      |
+| symbol      | Short ticker symbol                                                  |
+| uri         | Optional link to token image or extended metadata (e.g. IPFS)       |
+| uri_hash    | Hash of the URI content for integrity verification                   |
+
+### `pagination`
+
+| Field    | Description                                                                   |
+| -------- | ----------------------------------------------------------------------------- |
+| next_key | Base64-encoded cursor for the next page. `null` when all results are returned |
+| total    | Total number of denoms with registered metadata on the chain                  |
+
+### `fetchDenomMetadata` vs `fetchAllDenomsMetadata`
+
+| Feature               | fetchDenomMetadata        | fetchAllDenomsMetadata         |
+| --------------------- | ------------------------- | ------------------------------ |
+| Targets specific denom | ✅ Yes                   | ❌ Returns all denoms          |
+| Response size         | Minimal                   | Large (paginated, 2963+ items) |
+| Use case              | Single token info lookup  | Full metadata index            |
+
+## When to Use
+
+* Building a token registry or explorer index
+* Populating token lists with names, symbols and icons
+* Indexing all factory token metadata
+* Resolving display units and decimal precision for all tokens at once
 
 ---
 
-## `fetchSendEnabled`
+# 8️⃣ fetchSendEnabled
+
+## Method
 
-Query which denominations are **allowed to be transferred** on the chain.
+```ts
+async fetchSendEnabled()
+```
 
-**CLI equivalent**
+## CLI Equivalent
 
 ```bash
 zigchaind query bank send-enabled
 ```
 
-**Method**
+## Description
 
-```ts
-fetchSendEnabled()
-```
+Fetches the list of **per-denom send restrictions** configured on the chain.
 
-**Example**
+By default, all tokens are sendable. This endpoint only returns entries for denoms where the default has been **explicitly overridden** — either to disable sending for a normally-enabled denom, or enable it for a restricted one.
+
+The overall default send behaviour is governed by `fetchParams` (`default_send_enabled`).
+
+## Parameters
+
+None.
+
+## Usage Example
 
 ```ts
 const sendEnabled = await bankApi.fetchSendEnabled()
-console.log(sendEnabled)
+console.dir(sendEnabled, { depth: null })
 ```
 
+## Example Response
+
+```json
+{
+  "send_enabled": [],
+  "pagination": {
+    "next_key": null,
+    "total": "0"
+  }
+}
+```
+
+## Response Field Explanation
+
+### `send_enabled`
+
+Array of per-denom send override entries.
+
+An **empty array** means no denoms have had their default send behaviour overridden — this is the normal healthy state of the chain.
+
+If entries are present, each would contain:
+
+| Field   | Description                                              |
+| ------- | -------------------------------------------------------- |
+| denom   | Token denomination with a send override applied          |
+| enabled | `true` if sending is explicitly enabled, `false` if disabled |
+
+### `pagination`
+
+| Field    | Description                                           |
+| -------- | ----------------------------------------------------- |
+| next_key | Cursor for next page. `null` if no more results       |
+| total    | Number of denoms with explicit send overrides         |
+
+> On ZigChain testnet, `send_enabled` is empty and `total` is `0` — meaning all tokens follow the default send behaviour defined in bank params (`default_send_enabled: true`).
+
+## When to Use
+
+* Verifying whether a specific token can be transferred
+* Chain governance monitoring for send restriction changes
+
 ---
 
-## `fetchSpendableBalance`
+# 9️⃣ fetchSpendableBalance
+
+## Method
 
-Query the **spendable (usable) balance** of a specific token for an account.
-This excludes locked or vesting tokens.
+```ts
+async fetchSpendableBalance(address: string, denom: string)
+```
 
-**CLI equivalent**
+## CLI Equivalent
 
 ```bash
 zigchaind query bank spendable-balance <address> <denom>
 ```
 
-**Method**
+## Description
 
-```ts
-fetchSpendableBalance(address: string, denom: string)
-```
+Fetches the **spendable balance** of a specific denom for an account.
 
-**Example**
+The spendable balance is the portion of an account's holdings that is **immediately available** for use. It excludes any tokens that are locked, bonded or otherwise restricted.
+
+
+## Parameters
+
+| Name    | Type   | Description                                   |
+| ------- | ------ | --------------------------------------------- |
+| address | string | Bech32 address of the account to query        |
+| denom   | string | Token denomination to query spendable balance for |
+
+---
+
+## Usage Example
 
 ```ts
-const spendable = await bankApi.fetchSpendableBalance(
-  'zig1svkn4sqrlz8r6krq96ty6kze54n2ec03u0vat5',
-  'uzig'
-)
+const spendable = await bankApi.fetchSpendableBalance(address, 'uzig')
+console.dir(spendable, { depth: null })
+```
+
+## Example Response
 
-console.log(spendable)
+```json
+{
+  "balance": {
+    "denom": "uzig",
+    "amount": "443143284"
+  }
+}
 ```
 
+## Response Field Explanation
+
+### `balance`
+
+| Field  | Description                                               |
+| ------ | --------------------------------------------------------- |
+| denom  | The queried token denomination                            |
+| amount | Spendable (unlocked, available) amount, as a string       |
+
+### `fetchBalance` vs `fetchSpendableBalance`
+
+| Feature              | fetchBalance              | fetchSpendableBalance           |
+| -------------------- | ------------------------- | ------------------------------- |
+| Includes locked tokens | ✅ Yes (total balance)  | ❌ No (available only)          |
+| Useful for vesting accounts | ❌ May overstate   | ✅ Accurate available amount    |
+| Use case             | Total holdings inspection | Transaction pre-flight checks   |
+
+## When to Use
+
+* Checking available funds before sending a transaction
+* Wallet UIs displaying spendable vs total balance
+
 ---
 
-## `fetchSpendableBalances`
+# 🔟 fetchSpendableBalances
 
-Query **all spendable balances** for an account across all denominations.
+## Method
 
-**CLI equivalent**
+```ts
+async fetchSpendableBalances(address: string)
+```
+
+## CLI Equivalent
 
 ```bash
 zigchaind query bank spendable-balances <address>
 ```
 
-**Method**
+## Description
 
-```ts
-fetchSpendableBalances(address: string)
-```
+Fetches the **spendable balance across all denoms** for an account.
+
+This is the bulk version of `fetchSpendableBalance` — instead of querying one denom at a time, it returns all spendable token balances for the address in a single paginated response.
+
+For standard accounts, this will match `fetchBalances`. For vesting accounts, amounts may differ.
+
+## Parameters
 
-**Example**
+| Name    | Type   | Description                            |
+| ------- | ------ | -------------------------------------- |
+| address | string | Bech32 address of the account to query |
+
+---
+
+## Usage Example
 
 ```ts
-const spendableBalances = await bankApi.fetchSpendableBalances(
-  'zig1svkn4sqrlz8r6krq96ty6kze54n2ec03u0vat5'
-)
+const spendableBalances = await bankApi.fetchSpendableBalances(address)
+console.dir(spendableBalances, { depth: null })
+```
 
-console.log(spendableBalances)
+## Example Response
+
+```json
+{
+  "balances": [
+    {
+      "denom": "coin.zig1zpnw5dtzzttmgtdjgtywt08wnlyyskpuupy3cfw8mytlslx54j9sgz6w4n.oroswap",
+      "amount": "222026"
+    },
+    {
+      "denom": "uzig",
+      "amount": "443143284"
+    }
+  ],
+  "pagination": {
+    "next_key": null,
+    "total": "2"
+  }
+}
 ```
 
+## Response Field Explanation
+
+### `balances`
+
+Array of spendable token balances across all held denoms.
+
+| Field  | Description                                      |
+| ------ | ------------------------------------------------ |
+| denom  | Token denomination                               |
+| amount | Spendable (unlocked, available) amount as string |
+
+### `pagination`
+
+| Field    | Description                                           |
+| -------- | ----------------------------------------------------- |
+| next_key | Cursor for next page. `null` if no more results       |
+| total    | Total number of spendable denom balances              |
+
+## When to Use
+
+* Full portfolio view showing only available funds
+
 ---
 
-## `fetchParams`
+# 1️⃣1️⃣ fetchParams
+
+## Method
 
-Query the **bank module parameters**, such as send rules and token behavior.
+```ts
+async fetchParams()
+```
 
-**CLI equivalent**
+## CLI Equivalent
 
 ```bash
 zigchaind query bank params
-zigchaind query bank params --height <H>
 ```
 
-**Method**
+## Description
 
-```ts
-fetchParams()
-```
+Fetches the **Bank module parameters** configured at chain level.
+
+These are governance-controlled settings that define the default token transfer behaviour for the entire chain. Currently, the key parameter is `default_send_enabled` which acts as the chain-wide default for whether tokens can be sent.
 
-**Example**
+## Parameters
+
+None.
+
+## Usage Example
 
 ```ts
 const params = await bankApi.fetchParams()
-console.log(params)
+console.dir(params, { depth: null })
 ```
 
+## Example Response
+
+```json
+{
+  "params": {
+    "send_enabled": [],
+    "default_send_enabled": true
+  }
+}
+```
+
+## Response Field Explanation
+
+### `params`
+
+| Field                | Description                                                                    |
+| -------------------- | ------------------------------------------------------------------------------ |
+| send_enabled         | Array of per-denom send overrides. Empty means no overrides are set            |
+| default_send_enabled | Chain-wide default — `true` means all tokens are sendable unless overridden    |
+
+> `default_send_enabled: true` combined with an empty `send_enabled` array means **all tokens on the chain are freely transferable** with no restrictions. This is the normal operating state of ZigChain.
+
+## When to Use
+
+* Checking the chain-wide default transfer policy
+* Governance monitoring for parameter change proposals
+* Building chain configuration or status dashboards
+* Security auditing of token transfer rules
+
 ---