feat(cli): add derive-missing command for existing wallets

- Add 'derive-missing' command to coinpay-wallet CLI for bots to
  derive addresses for newly supported chains on existing wallets
- Update WebWalletDocs with derive-missing command documentation
- Add dedicated 'Upgrading Existing Wallets' section with SDK + CLI examples
- Update environment variable docs to note COINPAY_MNEMONIC requirement

This allows bots with existing wallets to easily add support for new
coins when they're added to the platform without creating a new wallet.

Author: ralyodio

scripts/coinpay-wallet.mjs

@@ -12,10 +12,12 @@
  *   pnpm coinpay-wallet send <wallet-id> --from <addr> --to <addr> --chain <chain> --amount <amount>
  *   pnpm coinpay-wallet address <wallet-id> [--chain <chain>]
  *   pnpm coinpay-wallet history <wallet-id> [--chain <chain>] [--limit <n>]
+ *   pnpm coinpay-wallet derive-missing <wallet-id> [--chains BTC,ETH,...]
  *
  * Configuration:
  *   COINPAY_API_URL   - API base URL (default: http://localhost:8080)
  *   COINPAY_AUTH_TOKEN - JWT auth token (for read-only operations)
+ *   COINPAY_MNEMONIC  - Mnemonic phrase (required for send and derive-missing)
  *
  *   Or use a config file at ~/.coinpayrc.json:
  *   { "apiUrl": "https://coinpayportal.com", "authToken": "..." }
@@ -333,6 +335,69 @@ async function cmdSync(positional, flags, config) {
   console.log(`  Synced: ${JSON.stringify(result)}\n`);
 }
 
+async function cmdDeriveMissing(positional, flags, config) {
+  const walletId = positional[0];
+  if (!walletId) {
+    error('Usage: coinpay-wallet derive-missing <wallet-id> [--chains BTC,ETH,...]');
+  }
+
+  // Require mnemonic for deriving addresses
+  const mnemonic = process.env.COINPAY_MNEMONIC;
+  if (!mnemonic) {
+    error('COINPAY_MNEMONIC is required to derive new addresses.');
+  }
+
+  const { Wallet } = await import('../src/lib/wallet-sdk/index.ts');
+
+  // Parse target chains if provided
+  const targetChains = flags.chains
+    ? flags.chains.split(',').map((c) => c.trim().toUpperCase())
+    : undefined; // undefined means use default supported chains
+
+  console.log(`\nChecking for missing chains on wallet ${walletId}...\n`);
+
+  // First, create wallet from seed to get the wallet instance
+  const wallet = await Wallet.fromSeed(mnemonic, {
+    baseUrl: config.apiUrl,
+    chains: ['BTC', 'BCH', 'ETH', 'POL', 'SOL'], // minimal chains for auth
+  });
+
+  if (wallet.walletId !== walletId) {
+    error(`Mnemonic wallet ID (${wallet.walletId}) doesn't match requested ID (${walletId})`);
+  }
+
+  // Check what's missing
+  const missingChains = await wallet.getMissingChains(targetChains);
+
+  if (missingChains.length === 0) {
+    console.log('  ✓ No missing chains! All addresses are already derived.\n');
+    return;
+  }
+
+  console.log(`  Missing chains: ${missingChains.join(', ')}\n`);
+  console.log('  Deriving addresses...\n');
+
+  // Derive the missing chains
+  const results = await wallet.deriveMissingChains(targetChains);
+
+  if (results.length === 0) {
+    console.log('  No new addresses derived.\n');
+    return;
+  }
+
+  console.log('  New addresses derived:\n');
+  printTable(
+    results.map((r) => ({
+      Chain: r.chain,
+      Address: r.address.length > 30
+        ? r.address.slice(0, 15) + '...' + r.address.slice(-10)
+        : r.address,
+      Index: r.derivationIndex,
+    }))
+  );
+  console.log();
+}
+
 // ── Help ──
 
 function showHelp() {
@@ -369,6 +434,9 @@ Commands:
   sync <wallet-id>      Sync on-chain transaction history
     --chain <chain>     Sync specific chain only
 
+  derive-missing <wallet-id>  Derive addresses for newly supported chains
+    --chains <list>     Target chains (default: BTC,BCH,ETH,POL,SOL,USDC_*)
+
 Environment Variables:
   COINPAY_API_URL       API base URL (default: http://localhost:8080)
   COINPAY_AUTH_TOKEN    JWT auth token for read-only operations
@@ -413,6 +481,9 @@ async function main() {
       case 'sync':
         await cmdSync(positional, flags, config);
         break;
+      case 'derive-missing':
+        await cmdDeriveMissing(positional, flags, config);
+        break;
       default:
         error(`Unknown command: ${command}\nRun 'coinpay-wallet help' for usage.`);
     }

src/components/docs/WebWalletDocs.tsx

@@ -78,6 +78,7 @@ pnpm coinpay-wallet create --chains BTC,ETH,SOL`}
           { cmd: 'send', args: '<wallet-id> --from <addr> --to <addr> --chain ETH --amount 0.5', desc: 'Send a transaction' },
           { cmd: 'history', args: '<wallet-id> --chain BTC --limit 20', desc: 'View transaction history' },
           { cmd: 'sync', args: '<wallet-id> --chain SOL', desc: 'Sync on-chain deposits into history' },
+          { cmd: 'derive-missing', args: '<wallet-id> [--chains BTC,ETH,...]', desc: 'Derive addresses for newly supported chains' },
         ].map((c) => (
           <div key={c.cmd} className="flex items-start gap-4 p-3 rounded-lg bg-slate-800/50">
             <code className="text-purple-400 font-mono text-sm whitespace-nowrap shrink-0">coinpay-wallet {c.cmd}</code>
@@ -94,7 +95,7 @@ pnpm coinpay-wallet create --chains BTC,ETH,SOL`}
         <div className="space-y-1 text-sm text-gray-300">
           <p><code className="text-purple-400">COINPAY_API_URL</code> — API base URL (default: <code>http://localhost:8080</code>)</p>
           <p><code className="text-purple-400">COINPAY_AUTH_TOKEN</code> — JWT token for read-only operations</p>
-          <p><code className="text-purple-400">COINPAY_MNEMONIC</code> — Mnemonic phrase (required for <code>send</code>)</p>
+          <p><code className="text-purple-400">COINPAY_MNEMONIC</code> — Mnemonic phrase (required for <code>send</code> and <code>derive-missing</code>)</p>
         </div>
         <p className="text-gray-500 text-xs mt-2">Or use a config file: <code>~/.coinpayrc.json</code></p>
       </div>
@@ -161,6 +162,54 @@ const newAddr = await wallet.deriveAddress('BTC');`}
         </CodeBlock>
       </div>
 
+      {/* Upgrading Wallets - Derive Missing Chains */}
+      <h3 className="text-xl font-semibold text-white mb-4">Upgrading Existing Wallets</h3>
+      <div className="mb-8 p-4 bg-amber-500/10 border border-amber-500/20 rounded-lg">
+        <div className="flex items-center gap-2 mb-2">
+          <span className="text-amber-400 font-semibold">🔄 New Chains Added?</span>
+        </div>
+        <p className="text-amber-300 text-sm mb-3">
+          When CoinPayPortal adds support for new coins, existing wallets won&apos;t have addresses for them. 
+          Use <code className="text-amber-200">deriveMissingChains()</code> to automatically derive addresses for any missing chains.
+        </p>
+        <CodeBlock title="Node.js SDK — Derive Missing Chains" language="javascript">
+{`import { Wallet } from '@coinpayportal/wallet-sdk';
+
+// Load your existing wallet from seed
+const wallet = await Wallet.fromSeed(process.env.WALLET_MNEMONIC, {
+  baseUrl: 'https://coinpayportal.com',
+  chains: ['BTC', 'ETH'], // minimal chains for auth
+});
+
+// Check which chains are missing
+const missing = await wallet.getMissingChains();
+console.log('Missing chains:', missing);
+// ['BCH', 'POL', 'SOL', 'USDC_ETH', 'USDC_POL', 'USDC_SOL']
+
+// Derive all missing chains at once
+const newAddresses = await wallet.deriveMissingChains();
+console.log('New addresses:', newAddresses);
+// [{ chain: 'BCH', address: 'bitcoincash:q...' }, ...]`}
+        </CodeBlock>
+        <div className="mt-4">
+          <h4 className="text-white font-semibold text-sm mb-2">CLI Command (for bots)</h4>
+          <CodeBlock title="Terminal" language="bash">
+{`# Check and derive missing chains
+export COINPAY_MNEMONIC="your twelve word seed phrase here"
+pnpm coinpay-wallet derive-missing <wallet-id>
+
+# Output:
+# Missing chains: BCH, POL, SOL, USDC_ETH, USDC_POL, USDC_SOL
+# Deriving addresses...
+# New addresses derived:
+#   Chain      Address                    Index
+#   BCH        bitcoincash:q...           0
+#   POL        0x...                      0
+#   ...`}
+          </CodeBlock>
+        </div>
+      </div>
+
       {/* Wallet Creation */}
       <ApiEndpoint method="POST" path="/api/web-wallet/create" description="Register a new wallet. Client generates seed phrase and HD keys locally, then sends only public keys. Include initial_addresses for all chains to have addresses ready immediately — no separate derive calls needed.">
         <div className="mb-4 p-4 bg-green-500/10 border border-green-500/20 rounded-lg">