feat: add getBalance() documentation and patterns

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/simple-mcp",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "MCP server for @bsv/simple — AI-assisted BSV blockchain development",
   "main": "dist/index.js",
   "bin": {

src/resources/api-reference.ts

@@ -30,6 +30,30 @@ const wallet = await ServerWallet.create({
 - \`getStatus(): WalletStatus\` — { isConnected, identityKey, network }
 - \`getWalletInfo(): WalletInfo\` — { identityKey, address, network, isConnected }
 - \`getClient(): WalletInterface\` — Underlying SDK wallet client
+- \`getBalance(basket?: string): Promise<BalanceResult>\` — Wallet balance (optimized via specOp when no basket, per-basket when specified)
+
+### Balance
+\`\`\`typescript
+interface BalanceResult {
+  totalSatoshis: number      // sum of all output satoshis
+  totalOutputs: number       // count of outputs (0 when using default specOp mode)
+  spendableSatoshis: number  // sum of spendable output satoshis
+  spendableOutputs: number   // count of spendable outputs (0 when using default specOp mode)
+}
+\`\`\`
+
+- **Without basket:** Uses wallet-toolbox \`specOpWalletBalance\` for an optimized query — balance computed at the storage layer. \`totalOutputs\`/\`spendableOutputs\` are 0.
+- **With basket:** Iterates outputs from \`listOutputs({ basket })\` to compute totals and separate spendable vs non-spendable.
+
+\`\`\`typescript
+// Overall wallet balance
+const balance = await wallet.getBalance()
+console.log(balance.totalSatoshis)  // total spendable sats
+
+// Per-basket balance
+const tokenBalance = await wallet.getBalance('tokens')
+console.log(tokenBalance.spendableSatoshis, tokenBalance.spendableOutputs)
+\`\`\`
 
 ### Key Derivation
 - \`derivePublicKey(protocolID: [SecurityLevel, string], keyID: string, counterparty?: string, forSelf?: boolean): Promise<string>\` — Derive public key for any protocol
@@ -112,6 +136,7 @@ interface SendOutputSpec {
 interface TransactionResult { txid: string; tx: any; outputs?: OutputInfo[] }
 interface SendResult extends TransactionResult { outputDetails: SendOutputDetail[] }
 interface SendOutputDetail { index: number; type: 'p2pkh' | 'op_return' | 'pushdrop'; satoshis: number; description: string }
+interface BalanceResult { totalSatoshis: number; totalOutputs: number; spendableSatoshis: number; spendableOutputs: number }
 \`\`\`
 `
 

src/resources/patterns.ts

@@ -34,6 +34,18 @@ export default function Page() {
 }
 \`\`\`
 
+## Pattern 1b: Check Wallet Balance
+\`\`\`typescript
+// Overall wallet balance (optimized — no output iteration)
+const balance = await wallet.getBalance()
+console.log(\`Wallet balance: \${balance.totalSatoshis} sats\`)
+
+// Per-basket balance (iterates outputs, shows spendable vs total)
+const tokenBalance = await wallet.getBalance('tokens')
+console.log(\`Tokens: \${tokenBalance.spendableOutputs} spendable (\${tokenBalance.spendableSatoshis} sats)\`)
+console.log(\`Total: \${tokenBalance.totalOutputs} outputs (\${tokenBalance.totalSatoshis} sats)\`)
+\`\`\`
+
 ## Pattern 2: Simple Payment via MessageBox P2P
 \`\`\`typescript
 const result = await wallet.pay({

src/tools/wallet.ts

@@ -76,6 +76,10 @@ async function main() {
   console.log('Connected:', wallet.getIdentityKey())
   console.log('Address:', wallet.getAddress())
   console.log('Status:', wallet.getStatus())
+
+  // Check balance
+  const balance = await wallet.getBalance()
+  console.log('Balance:', balance.totalSatoshis, 'sats')
 }
 
 main().catch(console.error)
@@ -101,7 +105,7 @@ Handles lazy-init singleton, key persistence, and all actions automatically.
 **API endpoints:**
 - \`GET ?action=create\` → server identity key + status
 - \`GET ?action=request&satoshis=1000\` → BRC-29 payment request
-- \`GET ?action=balance\` → output count + total satoshis
+- \`GET ?action=balance&basket=...\` → BalanceResult (uses \`getBalance()\` — optimized specOp when no basket)
 - \`POST ?action=receive\` body: \`{ tx, senderIdentityKey, derivationPrefix, derivationSuffix, outputIndex }\`
 
 No \`@bsv/sdk\` import needed. Add \`.server-wallet.json\` to \`.gitignore\`.`