sncast balance docs (#3818)

<!-- Reference any GitHub issues resolved by this PR -->

Closes #2319 

**Stack**:
- #3818 ⬅
- #3817

## Introduced changes

Add docs for `sncast utils balance`

## Checklist

<!-- Make sure all of these are complete -->

- [x] Linked relevant issue
- [x] Updated relevant documentation
- [x] Added relevant tests
- [x] Performed self-review of the code
- [x] Added changes to `CHANGELOG.md`

Author: franciszekjob

CHANGELOG.md

@@ -31,6 +31,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Possibility to use [`starknet-devnet`](https://github.com/0xSpaceShard/starknet-devnet) predeployed accounts directly in `sncast` without needing to import them. They are available under specific names - `devnet-1`, `devnet-2`, ..., `devnet-<N>`. Read more [here](https://foundry-rs.github.io/starknet-foundry/starknet/integration_with_devnet.html#predeployed-accounts)
 - Support for `--network devnet` flag that attempts to auto-detect running `starknet-devnet` instance and connect to it.
 - Support for automatically declaring the contract when running `sncast deploy`, by providing `--contract-name` flag instead of `--class-hash`. 
+- `sncast balance` command to fetch the balance of an account for a specified token.
 
 ## [0.50.0] - 2025-09-29
 

docs/src/SUMMARY.md

@@ -48,6 +48,7 @@
 * [Outline](starknet/sncast-overview.md)
 * [`sncast` 101](starknet/101.md)
 * [Creating And Deploying Accounts](starknet/account.md)
+* [Account Balance](starknet/account-balance.md)
 * [Importing Accounts](starknet/account-import.md)
 * [Declaring New Contracts](starknet/declare.md)
 * [Deploying New Contracts](starknet/deploy.md)
@@ -136,6 +137,7 @@
         * [deploy](appendix/sncast/account/deploy.md)
         * [delete](appendix/sncast/account/delete.md)
         * [list](appendix/sncast/account/list.md)
+    * [balance](appendix/sncast/balance.md)
     * [declare](appendix/sncast/declare.md)
     * [declare-from](appendix/sncast/declare_from.md)
     * [deploy](appendix/sncast/deploy.md)

docs/src/appendix/sncast.md

@@ -6,6 +6,7 @@
     * [create](./sncast/account/create.md)
     * [deploy](./sncast/account/deploy.md)
     * [delete](./sncast/account/delete.md)
+* [balance](./sncast/balance.md)
 * [declare](./sncast/declare.md)
 * [declare-from](./sncast/declare_from.md)
 * [deploy](./sncast/deploy.md)

docs/src/appendix/sncast/balance.md

@@ -0,0 +1,37 @@
+# `balance`
+Fetch balance of the account for specified token.
+
+## `--token, -t <TOKEN>`
+Optional.
+Conflicts with: [`--token-address`](#--token-address)
+
+Name of the token to check the balance for. Possible values
+- `strk` (default)
+- `eth`
+
+## `--token-address, -d <TOKEN_ADDRESS>`
+Optional.
+Conflicts with: [`--token`](#--token)
+
+Token contract address to check the balance for. Token needs to be compatible with ERC-20 standard.
+
+## `--block-id, -b <BLOCK_ID>`
+Optional.
+
+Block identifier on which balance should be fetched
+Possible values: `pending`, `latest`, block hash (0x prefixed string), and block number (u64).
+`pending` is used as a default value.
+
+## `--url, -u <RPC_URL>`
+Optional.
+
+Starknet RPC node url address.
+
+Overrides url from `snfoundry.toml`.
+
+## `--network <NETWORK>`
+Optional.
+
+Use predefined network with public provider
+
+Possible values: `mainnet`, `sepolia`.

docs/src/starknet/101.md

@@ -62,6 +62,21 @@ transaction: https://sepolia.starkscan.co/tx/0x[..]
 
 </details>
 
+Finally, you can check the account balance:
+
+<!-- { "ignored": true } -->
+```shell
+$ sncast --account my_account balance --network sepolia
+```
+
+<details>
+<summary>Output:</summary>
+
+```shell
+Balance: [..] strk
+```
+</details>
+
 Read more about accounts [here](./account-import.md)
 
 > 💡 **Tip**

docs/src/starknet/account-balance.md

@@ -0,0 +1,43 @@
+# Account Balance
+
+`sncast` allows you to check the balance of your account using the `sncast balance` command.
+
+## Basic Example
+
+```shell
+$ sncast --account my_account balance --network devnet
+```
+
+<details>
+<summary>Output:</summary>
+
+```shell
+Balance: [..] strk
+```
+</details>
+
+By default, it shows the balance in STRK tokens. Other possible tokens can be specified using the `--token` flag, read more [here](../appendix/sncast/balance.html#--token--t-token).
+
+## Checking Balance of a Custom Token
+
+You can check the balance of a custom token by providing the `--token-address` flag followed by the token's contract address.
+
+> 📝 **Note**
+>
+> Token address must be a valid ERC-20 token contract.
+
+<!-- { "ignored": true } -->
+```shell
+$ sncast --account user1 balance \
+    --token-address <YOUR_TOKEN_ADDRESS> \
+    --network sepolia
+```
+
+<details>
+<summary>Output:</summary>
+```shell
+Balance: [..]
+```
+</details>
+
+Read more about `sncast balance` command [here](../appendix/sncast/balance.md).