apow-cli 0.4.1 → 0.6.1

package/dist/index.js

@@ -170,27 +170,10 @@ async function setupWizard() {
     console.log("");
     // Step 2: RPC
     console.log(`  ${ui.bold("Step 2/3: RPC")}`);
-    const rpcUrl = await ui.prompt("Base RPC URL", "https://mainnet.base.org");
-    values.RPC_URL = rpcUrl;
-    // Validate RPC connectivity
-    try {
-        const { createPublicClient, http } = await Promise.resolve().then(() => __importStar(require("viem")));
-        const { base, baseSepolia } = await Promise.resolve().then(() => __importStar(require("viem/chains")));
-        const isSepolia = rpcUrl.toLowerCase().includes("sepolia");
-        const testClient = createPublicClient({
-            chain: isSepolia ? baseSepolia : base,
-            transport: http(rpcUrl),
-        });
-        const blockNumber = await testClient.getBlockNumber();
-        const networkName = isSepolia ? "Base Sepolia" : "Base mainnet";
-        ui.ok(`Connected — ${networkName}, block #${blockNumber.toLocaleString()}`);
-        if (isSepolia)
-            values.CHAIN = "baseSepolia";
-    }
-    catch {
-        ui.fail("Could not connect to RPC");
-        ui.hint("Continuing anyway — you can fix RPC_URL in .env later");
-    }
+    console.log(`  ${ui.dim("Default: Alchemy x402 — premium RPC paid automatically")}`);
+    console.log(`  ${ui.dim("via USDC in your mining wallet. No API key needed.")}`);
+    console.log(`  ${ui.dim("To use a custom RPC, set RPC_URL in .env after setup.")}`);
+    ui.ok("RPC: Alchemy x402 (default)");
     console.log("");
     // Step 3: LLM (for minting)
     console.log(`  ${ui.bold("Step 3/3: LLM Provider (for minting)")}`);
@@ -277,10 +260,12 @@ async function main() {
     });
     program
         .command("fund")
-        .description("Fund your wallet — bridge SOL → ETH on Base, or show deposit address")
-        .option("--solana", "Bridge from Solana")
+        .description("Fund your wallet — bridge from Solana/Ethereum or swap on Base")
+        .option("--chain <chain>", "Source chain: solana, ethereum, base")
+        .option("--token <token>", "Source token: sol, eth, usdc")
         .option("--key <base58>", "Solana private key for direct signing")
         .option("--amount <eth>", "Target ETH amount (default: 0.005)")
+        .option("--no-swap", "Skip auto-split after bridging")
         .hook("preAction", async () => {
         await (0, preflight_1.runPreflight)("readonly");
     })
@@ -513,6 +498,8 @@ async function main() {
             port: 3847,
             walletsPath,
             rpcUrl: config_1.config.rpcUrl,
+            useX402: config_1.config.useX402,
+            privateKey: config_1.config.privateKey,
             miningAgentAddress: config_1.config.miningAgentAddress,
             agentCoinAddress: config_1.config.agentCoinAddress,
         });

package/dist/preflight.js

@@ -38,11 +38,24 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runPreflight = runPreflight;
 const viem_1 = require("viem");
+const chains_1 = require("viem/chains");
 const AgentCoin_json_1 = __importDefault(require("./abi/AgentCoin.json"));
 const config_1 = require("./config");
 const wallet_1 = require("./wallet");
+const x402_1 = require("./x402");
 const ui = __importStar(require("./ui"));
 const agentCoinAbi = AgentCoin_json_1.default;
+const USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+const USDC_DECIMALS = 6;
+const erc20BalanceAbi = [
+    {
+        type: "function",
+        name: "balanceOf",
+        inputs: [{ name: "account", type: "address" }],
+        outputs: [{ name: "", type: "uint256" }],
+        stateMutability: "view",
+    },
+];
 async function runPreflight(level) {
     const results = [];
     // Check 1: Contract addresses set
@@ -79,6 +92,45 @@ async function runPreflight(level) {
             fix: "Check internet connection or update RPC_URL in .env",
         });
     }
+    // Check x402: USDC balance when x402 mode is active
+    if (config_1.config.useX402 && wallet_1.account) {
+        try {
+            // Use a separate lightweight client to avoid chicken-and-egg
+            // (can't use x402 to check if we can pay for x402)
+            const checkClient = (0, viem_1.createPublicClient)({
+                chain: chains_1.base,
+                transport: (0, viem_1.http)("https://mainnet.base.org"),
+            });
+            const usdcBalance = (await checkClient.readContract({
+                address: USDC_ADDRESS,
+                abi: erc20BalanceAbi,
+                functionName: "balanceOf",
+                args: [wallet_1.account.address],
+            }));
+            if (usdcBalance === 0n) {
+                ui.warn("No USDC balance — x402 RPC requires USDC on Base for payment");
+                ui.hint(`Send USDC to ${wallet_1.account.address} on Base, or set RPC_URL in .env to use a free RPC`);
+                ui.hint("Falling back to public RPC (https://mainnet.base.org)");
+                config_1.config.useX402 = false;
+                (0, x402_1.resetX402)();
+                (0, wallet_1.reinitClients)();
+            }
+            else {
+                const formatted = (0, viem_1.formatUnits)(usdcBalance, USDC_DECIMALS);
+                results.push({
+                    label: `RPC: Alchemy x402 (${formatted} USDC available)`,
+                    passed: true,
+                });
+            }
+        }
+        catch {
+            // USDC check failed — fall back silently
+            ui.warn("Could not check USDC balance — falling back to public RPC");
+            config_1.config.useX402 = false;
+            (0, x402_1.resetX402)();
+            (0, wallet_1.reinitClients)();
+        }
+    }
     if (level === "wallet" || level === "mining") {
         // Check 3: Private key valid
         if (wallet_1.account) {

package/dist/wallet.js

@@ -1,16 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.walletClient = exports.account = exports.publicClient = void 0;
+exports.reinitClients = reinitClients;
 exports.requireWallet = requireWallet;
 exports.getEthBalance = getEthBalance;
 const viem_1 = require("viem");
 const accounts_1 = require("viem/accounts");
 const erc8021_1 = require("ox/erc8021");
 const config_1 = require("./config");
+const x402_1 = require("./x402");
 const DATA_SUFFIX = erc8021_1.Attribution.toDataSuffix({ codes: ["bc_6wfeb1kd"] });
+function getTransport() {
+    if (config_1.config.useX402 && config_1.config.privateKey) {
+        return (0, x402_1.createX402Transport)(config_1.config.privateKey);
+    }
+    return (0, viem_1.http)(config_1.config.rpcUrl);
+}
+const transport = getTransport();
 exports.publicClient = (0, viem_1.createPublicClient)({
     chain: config_1.config.chain,
-    transport: (0, viem_1.http)(config_1.config.rpcUrl),
+    transport,
 });
 exports.account = config_1.config.privateKey
     ? (0, accounts_1.privateKeyToAccount)(config_1.config.privateKey)
@@ -19,10 +28,23 @@ exports.walletClient = exports.account
     ? (0, viem_1.createWalletClient)({
         account: exports.account,
         chain: config_1.config.chain,
-        transport: (0, viem_1.http)(config_1.config.rpcUrl),
+        transport,
         dataSuffix: DATA_SUFFIX,
     })
     : null;
+/** Reinitialize clients after config changes (e.g., x402 fallback). */
+function reinitClients() {
+    const t = getTransport();
+    exports.publicClient = (0, viem_1.createPublicClient)({ chain: config_1.config.chain, transport: t });
+    if (exports.account) {
+        exports.walletClient = (0, viem_1.createWalletClient)({
+            account: exports.account,
+            chain: config_1.config.chain,
+            transport: t,
+            dataSuffix: DATA_SUFFIX,
+        });
+    }
+}
 function requireWallet() {
     if (!exports.account || !exports.walletClient) {
         throw new Error("Wallet is not configured. Set PRIVATE_KEY in .env.");

package/dist/x402.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createX402Transport = createX402Transport;
+exports.resetX402 = resetX402;
+const accounts_1 = require("viem/accounts");
+const viem_1 = require("viem");
+const ALCHEMY_X402_BASE = "https://x402.alchemy.com/rpc/base-mainnet";
+let _paidFetch = null;
+/* eslint-disable @typescript-eslint/no-require-imports */
+function getPaidFetchSync(privateKey) {
+    if (_paidFetch)
+        return _paidFetch;
+    // Use require() to avoid subpath module resolution issues with CommonJS.
+    // The x402 packages use `exports` maps which require "node16"/"bundler"
+    // moduleResolution — but this project uses classic "Node" resolution.
+    const { x402Client } = require("@x402/core/client");
+    const { ExactEvmScheme } = require("@x402/evm/exact/client");
+    const { toClientEvmSigner } = require("@x402/evm");
+    const { wrapFetchWithPayment } = require("@x402/fetch");
+    const account = (0, accounts_1.privateKeyToAccount)(privateKey);
+    const signer = toClientEvmSigner(account);
+    const client = new x402Client();
+    client.register("eip155:*", new ExactEvmScheme(signer));
+    _paidFetch = wrapFetchWithPayment(fetch, client);
+    return _paidFetch;
+}
+function createX402Transport(privateKey) {
+    return (0, viem_1.custom)({
+        async request({ method, params }) {
+            const paidFetch = getPaidFetchSync(privateKey);
+            const response = await paidFetch(ALCHEMY_X402_BASE, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ jsonrpc: "2.0", method, params, id: 1 }),
+            });
+            const data = (await response.json());
+            if (data.error)
+                throw new Error(data.error.message);
+            return data.result;
+        },
+    });
+}
+function resetX402() {
+    _paidFetch = null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apow-cli",
-  "version": "0.4.1",
+  "version": "0.6.1",
   "description": "Mine AGENT tokens on Base L2 with Agentic Proof of Work",
   "keywords": [
     "apow",
@@ -40,6 +40,8 @@
   },
   "dependencies": {
     "@solana/web3.js": "^1.98.0",
+    "@x402/evm": "^2.8.0",
+    "@x402/fetch": "^2.8.0",
     "commander": "^14.0.0",
     "dotenv": "^17.2.3",
     "openai": "^6.6.0",

package/skill.md

@@ -25,14 +25,7 @@ metadata:
 configure the miner, mint, and mine. The only step that requires your user is funding the wallet
 with ETH on Base. Everything else you handle yourself.
 
-> **IMPORTANT: You need a dedicated RPC endpoint.** The default public RPC (`https://mainnet.base.org`) has aggressive rate limits and **will cause minting and mining to fail**. Before starting, get a free Alchemy endpoint:
->
-> 1. Go to [alchemy.com](https://www.alchemy.com/) and sign up (free, no credit card)
-> 2. Click **Create new app** → Name: `apow-miner` → Chain: **Base** → Network: **Base Mainnet**
-> 3. Copy the **HTTPS** URL: `https://base-mainnet.g.alchemy.com/v2/YOUR_API_KEY`
-> 4. Set `RPC_URL` to this URL in your `.env`
->
-> Alchemy's free tier (300M compute units/month) is more than enough. See [RPC Recommendations](#rpc-recommendations) for alternatives.
+> **RPC:** The CLI uses [Alchemy x402](https://x402.alchemy.com/) by default -- a premium Base RPC that charges per-request via USDC in your mining wallet. No API key, no account, no rate limits. Just fund your wallet with USDC (the `apow fund` command handles this automatically). If no USDC is available, it falls back to the public RPC. To use a custom RPC, set `RPC_URL` in `.env`.
 
 ---
 
@@ -78,10 +71,11 @@ MINING_AGENT_ADDRESS=0xB7caD3ca5F2BD8aEC2Eb67d6E8D448099B3bC03D
 AGENT_COIN_ADDRESS=0x12577CF0D8a07363224D6909c54C056A183e13b3
 EOF
 
-# 3. Fund the wallet (bridge from Solana or send ETH on Base)
-npx apow-cli fund --solana            # interactive bridge SOL → ETH on Base
-# Or: npx apow-cli fund --solana --key <base58>  # direct signing (~20s)
-# Or: ask your user to send ≥0.005 ETH on Base directly
+# 3. Fund the wallet (bridge from any chain, auto-splits into ETH + USDC)
+npx apow-cli fund --chain solana --token sol    # bridge SOL → ETH+USDC on Base
+# Or: npx apow-cli fund --chain solana --token sol --key <base58>  # direct signing (~20s)
+# Or: npx apow-cli fund --chain ethereum --token eth  # bridge from Ethereum mainnet
+# Or: ask your user to send ETH + USDC on Base directly
 
 # 4. Mint + mine (fully autonomous from here)
 npx apow-cli mint
@@ -117,7 +111,7 @@ The miner client validates locally before submitting.
 |---|---|
 | **Node.js** | v18 or higher |
 | **Base wallet** | A private key with ETH on Base (for gas + mint fee) |
-| **LLM access** | API key (OpenAI, Anthropic, Gemini, DeepSeek, Qwen), local Ollama, or Claude Code / Codex CLI (**required for minting only**) |
+| **LLM access** | API key (OpenAI, Gemini, DeepSeek, Qwen, or Anthropic) or local Ollama (**required for minting only**) |
 | **git** | Only if installing from source (not needed for npm) |
 
 ---
@@ -158,26 +152,32 @@ Your mining wallet needs ETH on Base for gas and the mint fee.
 
 ### Built-in Bridge: `apow fund` (Recommended)
 
-The CLI has a built-in cross-chain bridge for Solana users:
+The CLI accepts deposits in 6 forms across 3 chains, auto-bridges to Base, and auto-splits into ETH (gas) + USDC (x402 RPC):
 
 ```bash
-npx apow-cli fund                           # Interactive: choose funding method
-npx apow-cli fund --solana                  # Deposit address + QR code
-npx apow-cli fund --solana --key <base58>   # Direct Solana signing (~20s)
-npx apow-cli fund --solana --amount 0.01    # Custom ETH target
+npx apow-cli fund                                          # Interactive: choose chain + token
+npx apow-cli fund --chain solana --token sol               # Bridge SOL → ETH+USDC on Base
+npx apow-cli fund --chain solana --token sol --key <b58>   # Direct Solana signing (~20s)
+npx apow-cli fund --chain solana --token usdc              # Bridge Solana USDC → Base
+npx apow-cli fund --chain ethereum --token eth             # Bridge ETH from mainnet
+npx apow-cli fund --chain ethereum --token usdc            # Bridge USDC from mainnet
+npx apow-cli fund --chain base                             # Show address, wait for deposit
+npx apow-cli fund --chain base --no-swap                   # Skip auto-split
 ```
 
-**Three funding paths:**
+**Bridge methods per chain:**
+
+| Chain | Direct signing | Deposit address |
+|-------|---------------|-----------------|
+| Solana | deBridge DLN (~20s, `--key`) | Squid Router (~1-3 min) |
+| Ethereum | deBridge DLN (~20s, uses PRIVATE_KEY on mainnet) | Squid Router (~1-3 min) |
+| Base | N/A (already on Base) | Show address + QR code |
 
-| Path | How it works | Speed | Requires Solana key? |
-|------|-------------|-------|---------------------|
-| Direct signing | deBridge DLN signs + submits via your Solana keypair | ~20 seconds | Yes (`--key`) |
-| Deposit address | Squid Router generates a Solana address; send from any wallet | ~1-3 minutes | No |
-| Manual | Shows your Base address + QR code | Varies | No |
+**Auto-split:** After bridging, the CLI checks ETH and USDC balances. If either is below the minimum (0.003 ETH for gas, 2.00 USDC for x402 RPC), it swaps the needed amount via Uniswap V3 on Base. Use `--no-swap` to skip.
 
-**Direct signing (`--key`):** Provide your base58 Solana secret key. The CLI calls deBridge DLN to create a bridge order, signs the Solana transaction locally, submits it, and polls until ETH arrives on Base. No API key needed.
+**Direct signing (Solana `--key`):** Provide your base58 Solana secret key. The CLI calls deBridge DLN to create a bridge order, signs the Solana transaction locally, submits it, and polls until funds arrive on Base. No API key needed.
 
-**Deposit address (`--solana` without `--key`):** Requires `SQUID_INTEGRATOR_ID` in `.env` (free, apply at [squidrouter.com](https://app.squidrouter.com/)). Generates a one-time Solana deposit address with a QR code. Send SOL from any wallet (Phantom, Backpack, etc.) and the bridge handles the rest.
+**Deposit address (no `--key`):** Requires `SQUID_INTEGRATOR_ID` in `.env` (free, apply at [squidrouter.com](https://app.squidrouter.com/)). Generates a one-time deposit address with a QR code. Send tokens from any wallet and the bridge handles the rest.
 
 ### Manual Funding Options
 
@@ -247,7 +247,7 @@ AGENT_COIN_ADDRESS=0x12577CF0D8a07363224D6909c54C056A183e13b3
 
 # === LLM Configuration (required for minting only; mining uses optimized solving) ===
 
-# Provider: "openai" | "anthropic" | "ollama" | "gemini" | "deepseek" | "qwen" | "claude-code" | "codex"
+# Provider: "openai" | "gemini" | "deepseek" | "qwen" | "anthropic" | "ollama"
 LLM_PROVIDER=openai
 
 # API key (not required if LLM_PROVIDER=ollama)
@@ -273,32 +273,30 @@ CHAIN=base
 | `PRIVATE_KEY` | Yes | - | Wallet private key (0x + 64 hex chars) |
 | `MINING_AGENT_ADDRESS` | Yes | - | Deployed MiningAgent contract address |
 | `AGENT_COIN_ADDRESS` | Yes | - | Deployed AgentCoin contract address |
-| `LLM_PROVIDER` | For minting | `openai` | LLM provider for minting: `openai`, `anthropic`, `ollama`, `gemini`, `deepseek`, `qwen`, `claude-code`, or `codex`. Not needed for mining. |
-| `LLM_API_KEY` | For minting | - | API key for minting. Falls back to `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `GEMINI_API_KEY` / `DEEPSEEK_API_KEY` / `DASHSCOPE_API_KEY` per provider. Not needed for `ollama`, `claude-code`, `codex`, or mining. |
+| `LLM_PROVIDER` | For minting | `openai` | LLM provider for minting: `openai`, `gemini`, `deepseek`, `qwen`, `anthropic`, or `ollama`. Not needed for mining. |
+| `LLM_API_KEY` | For minting | - | API key for minting. Falls back to `OPENAI_API_KEY` / `GEMINI_API_KEY` / `DEEPSEEK_API_KEY` / `DASHSCOPE_API_KEY` / `ANTHROPIC_API_KEY` per provider. Not needed for `ollama` or mining. |
 | `LLM_MODEL` | For minting | `gpt-4o-mini` | Model identifier passed to the provider (minting only) |
 | `MINER_THREADS` | No | All CPU cores | Number of threads for parallel nonce grinding |
-| `RPC_URL` | **Strongly recommended** | `https://mainnet.base.org` | Base JSON-RPC endpoint. **The default public RPC is unreliable. Use Alchemy (free) or another dedicated provider.** |
+| `RPC_URL` | No | Alchemy x402 | Base JSON-RPC endpoint. Default uses Alchemy x402 (premium, paid via USDC). Set to override with a custom endpoint. |
 | `CHAIN` | No | `base` | Network selector; auto-detects `baseSepolia` if RPC URL contains "sepolia" |
-| `SOLANA_RPC_URL` | No | `https://api.mainnet-beta.solana.com` | Solana RPC endpoint (only for `apow fund --solana`) |
+| `SOLANA_RPC_URL` | No | `https://api.mainnet-beta.solana.com` | Solana RPC endpoint (only for `apow fund --chain solana`) |
+| `ETHEREUM_RPC_URL` | No | `https://ethereum-rpc.publicnode.com` | Ethereum mainnet RPC (only for `apow fund --chain ethereum`) |
 | `SQUID_INTEGRATOR_ID` | No | - | Squid Router integrator ID for deposit address flow (free at [squidrouter.com](https://app.squidrouter.com/)) |
 
 ### LLM Provider Recommendations (for Minting)
 
 > An LLM is only needed for **minting** your Mining Rig NFT (one-time identity verification). Mining uses optimized algorithmic SMHL solving, with no LLM needed.
 >
-> **For AI agents:** Use an API-based provider (OpenAI, Anthropic, Gemini, DeepSeek, or Qwen) for minting. Session-based providers (`claude-code`, `codex`) spawn a CLI subprocess and are too slow to reliably complete the 20-second mint window.
+> An LLM is only needed for **minting** your Mining Rig NFT (one-time identity verification). Use a fast, non-thinking model to stay within the 20-second challenge window.
 
 | Provider | Model | Cost per call | Notes |
 |---|---|---|---|
-| OpenAI | `gpt-4o-mini` | ~$0.001 | **Recommended for agents.** Cheapest, fastest, reliable |
+| OpenAI | `gpt-4o-mini` | ~$0.001 | **Recommended.** Cheapest, fastest, reliable |
 | Gemini | `gemini-2.5-flash` | ~$0.001 | Fast, good accuracy |
-| Anthropic | `claude-sonnet-4-5-20250929` | ~$0.005 | High accuracy on constrained generation |
-| OpenAI | `gpt-4o` | ~$0.005 | Higher quality, slightly slower |
 | DeepSeek | `deepseek-chat` | ~$0.001 | Fast, accessible in China |
 | Qwen | `qwen-plus` | ~$0.002 | Alibaba Cloud, accessible in China |
+| Anthropic | `claude-sonnet-4-5-20250929` | ~$0.005 | Works but slower and more expensive |
 | Ollama | `llama3.1` | Free (local) | Requires local GPU; variable accuracy |
-| Claude Code | `default` | Subscription | **Not recommended for minting.** CLI startup too slow for 20s window |
-| Codex | `default` | Subscription | **Not recommended for minting.** CLI startup too slow for 20s window |
 
 ### RPC Recommendations
 
@@ -369,7 +367,7 @@ npx apow-cli mint
 5. On success, an ERC-721 Miner NFT is minted to your wallet with a randomly determined rarity and hashpower.
 6. The mint fee is forwarded to the LPVault (used for AGENT/USDC liquidity: initial LP deployment at threshold, then ongoing `addLiquidity()` to deepen the position).
 
-**Challenge expiry:** 20 seconds from `getChallenge` to `mint`. The LLM must solve quickly. Use an API-based provider (openai/anthropic/gemini/deepseek/qwen). Session-based providers (claude-code/codex) are too slow and will fail.
+**Challenge expiry:** 20 seconds from `getChallenge` to `mint`. The LLM must solve quickly. Use a fast, non-thinking model (gpt-4o-mini, gemini-2.5-flash, deepseek-chat).
 
 ### Mint Price
 
@@ -535,6 +533,8 @@ pm2 logs
 
 **RPC rate limits:** For 3+ concurrent miners, use a dedicated RPC endpoint (Alchemy, Infura, QuickNode) instead of the default `https://mainnet.base.org`.
 
+**Want more hash power?** The nonce grinder scales linearly with CPU cores. Rent a high-core-count machine on [vast.ai](https://vast.ai/) to increase throughput. Not required, but effective for competitive mining.
+
 ### Local LLM Setup (Ollama)
 
 ```bash
@@ -554,30 +554,6 @@ Ollama runs on `http://127.0.0.1:11434` by default. The miner connects there aut
 
 **Trade-off:** Free inference, but local models may have lower accuracy on the constrained SMHL challenges. The miner retries up to 3 times per challenge, but persistent failures will slow mining.
 
-### Session Mining (Claude Code / Codex)
-
-Mine using your existing Claude Code or Codex subscription (no API key required):
-
-```bash
-# In your .env
-LLM_PROVIDER=claude-code
-# No LLM_API_KEY needed; the miner shells out to your local CLI
-```
-
-Or with Codex:
-```bash
-LLM_PROVIDER=codex
-```
-
-**How it works:** Instead of calling an LLM API, the miner executes `claude -p` or `codex exec` locally to solve SMHL challenges. This uses whatever model your CLI session defaults to.
-
-**Requirements:**
-- `claude` or `codex` CLI must be installed and authenticated
-- The CLI must be available in your PATH
-- Your subscription must be active
-
-**Warning:** Session-based providers (`claude-code`, `codex`) spawn a CLI subprocess for each SMHL challenge. The startup overhead frequently exceeds the 20-second mint challenge window, causing mints to fail with `Expired`. **For minting, always use an API-based provider** (openai, anthropic, gemini, deepseek, or qwen). Session providers may work for the mining loop (which has no time limit per challenge) but are unreliable and not recommended for autonomous operation.
-
 ### Custom RPC Endpoints
 
 Set `RPC_URL` in `.env` to any Base-compatible JSON-RPC endpoint. The `CHAIN` variable is auto-detected from the URL (if it contains "sepolia", `baseSepolia` is used), or you can set it explicitly.
@@ -619,7 +595,7 @@ Use the corresponding testnet contract addresses.
 | `LLM_API_KEY is required for openai.` | Missing API key for cloud provider | Set `LLM_API_KEY` (or provider-specific key like `OPENAI_API_KEY`) in `.env`, or switch to `ollama` |
 | `Insufficient fee` | Not enough ETH sent with mint | Check `getMintPrice()` and ensure wallet has enough ETH |
 | `Sold out` | All 10,000 Miner NFTs minted | No more rigs available; buy one on secondary market |
-| `Expired` | SMHL challenge expired (>20s) | Switch to an API-based provider (openai/gemini/anthropic/deepseek/qwen). Session providers (claude-code/codex) are too slow for the 20s mint window |
+| `Expired` | SMHL challenge expired (>20s) | Use a faster model (gpt-4o-mini, gemini-2.5-flash). Thinking models are too slow for the 20s mint window |
 | `Invalid SMHL` | LLM produced an incorrect solution | Retry; if persistent, switch to a more capable model |
 | `Not your miner` | Token ID not owned by your wallet | Verify `PRIVATE_KEY` matches the NFT owner; check token ID |
 | `Supply exhausted` | All 18.9M mineable AGENT has been minted | Mining is complete; no more rewards available |
@@ -632,8 +608,6 @@ Use the corresponding testnet contract addresses.
 | `SMHL solve failed after 3 attempts` | LLM cannot satisfy constraints | Switch to a more capable model (e.g., `gpt-4o` or `claude-sonnet-4-5-20250929`) |
 | `Fee forward failed` | LPVault rejected the ETH transfer | LPVault may not be set; check contract deployment |
 | `10 consecutive failures` | Repeated transient errors | Check RPC connectivity, wallet balance, and LLM availability |
-| `Claude Code error: ...` | `claude` CLI failed or timed out | Verify `claude` is installed and in PATH; check subscription is active |
-| `Codex error: ...` | `codex` CLI failed or timed out | Verify `codex` is installed and in PATH; check subscription is active |
 | `Timed out waiting for next block (60s)` | RPC not responding or network stalled | Check RPC connectivity; try a different RPC endpoint |
 
 ---
@@ -662,10 +636,11 @@ The CLI makes only these network calls:
 
 1. **Blockchain RPC** (to user-configured RPC URL, default: `mainnet.base.org`): standard `eth_call`, `eth_sendRawTransaction`, etc.
 2. **LLM API** (to user-configured provider): sends only word-puzzle prompts for SMHL solving, never wallet data
-3. **Bridge APIs** (only when using `apow fund --solana`):
+3. **Bridge APIs** (only when using `apow fund`):
    - **CoinGecko** (`api.coingecko.com`): SOL/ETH price quotes
    - **deBridge DLN** (`dln.debridge.finance`): bridge order creation and status (direct signing flow)
    - **Squid Router** (`v2.api.squidrouter.com`): deposit address generation (deposit address flow)
+   - **Uniswap V3** (on-chain, Base): ETH/USDC swaps for auto-split
    - **Solana RPC** (`api.mainnet-beta.solana.com` or custom): balance checks and tx submission
 
 No private keys are transmitted to bridge providers. deBridge returns a serialized Solana transaction that is signed locally. Squid generates a deposit address, and the user sends SOL themselves.
@@ -751,6 +726,82 @@ cat package.json | grep -A5 "scripts"  # no postinstall hook
 - **Standard:** ERC-721 Enumerable + ERC-8004 (Agent Registry)
 - **Max supply:** 10,000
 
+
+## 14. Dashboard
+
+The `apow dashboard` command group provides a real-time web UI for monitoring your entire mining fleet. Zero external dependencies — it serves vanilla HTML/JS directly from the CLI.
+
+### Subcommands
+
+| Command | Description |
+|---------|-------------|
+| `apow dashboard start` | Launch the dashboard web UI at `http://localhost:3847`. Auto-opens browser. Press Ctrl+C to stop. |
+| `apow dashboard add <address>` | Add a wallet address to monitor. Validates 0x + 40 hex chars. |
+| `apow dashboard remove <address>` | Remove a wallet address from monitoring. |
+| `apow dashboard scan [dir]` | Auto-detect wallets from `wallet-0x*.txt` files in the given directory (default: CWD). Also scans `rig*/` subdirectories. |
+| `apow dashboard wallets` | List all currently monitored wallet addresses. |
+
+### How It Works
+
+- **Wallet storage:** `~/.apow/wallets.json` — a plain JSON array of Ethereum addresses.
+- **Fleet management:** `~/.apow/fleets.json` — optional, defines named groups of wallets from different sources.
+- **Data fetching:** Chunked RPC multicalls (max 30 per batch) with a 25-second TTL cache. Queries ETH balance, AGENT balance, rig ownership, rarity, hashpower, mine count, and earnings for every wallet.
+- **NFT art:** Renders on-chain SVG art for each Mining Rig with rarity-based color coding.
+- **Auto-seed:** On first run, seeds `wallets.json` with the address from your `.env` if configured.
+- **Auto-detect:** `dashboard start` automatically scans CWD for `wallet-0x*.txt` files before launching.
+
+### Fleet Configuration (`~/.apow/fleets.json`)
+
+For managing wallets across multiple machines or directories, create `~/.apow/fleets.json`:
+
+```json
+[
+  { "name": "Local", "type": "array", "path": "/home/user/.apow/wallets.json" },
+  { "name": "Vast.ai Rigs", "type": "rigdirs", "path": "/mnt/mining/rigs" },
+  { "name": "Pool Wallets", "type": "walletfiles", "path": "/mnt/mining/wallets" },
+  { "name": "Solkek Fleet", "type": "solkek", "path": "/home/user/solkek-config.json" }
+]
+```
+
+**Fleet types:**
+
+| Type | Source Format | Description |
+|------|--------------|-------------|
+| `array` | JSON array of addresses | Simple list: `["0xABC...", "0xDEF..."]` |
+| `solkek` | JSON with `master.address` + `miners[].address` | Solkek fleet manager format |
+| `rigdirs` | Directory containing `rig*/wallet-0x*.txt` | Scan rig subdirectories for wallet files |
+| `walletfiles` | Directory containing `wallet-0x*.txt` | Scan flat directory for wallet files |
+
+If `fleets.json` does not exist, the dashboard falls back to `wallets.json` as a single "Main" fleet.
+
+### Example Workflow
+
+```bash
+# 1. Scan a directory with wallet files to populate wallets.json
+npx apow-cli dashboard scan /path/to/mining/dir
+
+# 2. Manually add a wallet not found by scan
+npx apow-cli dashboard add 0x1234567890abcdef1234567890abcdef12345678
+
+# 3. Verify your wallet list
+npx apow-cli dashboard wallets
+
+# 4. Launch the dashboard
+npx apow-cli dashboard start
+# → Opens http://localhost:3847 in your browser
+# → Shows real-time balances, rig stats, earnings, and NFT art
+# → Press Ctrl+C to stop
+```
+
+### Troubleshooting
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| "No wallets configured" | Empty `wallets.json` | Run `apow dashboard add <addr>` or `apow dashboard scan .` |
+| Dashboard shows 0 balances | RPC rate limiting | Set a dedicated `RPC_URL` in `.env` (Alchemy recommended) |
+| Browser doesn't open | Headless/SSH environment | Manually open `http://localhost:3847` in a browser |
+| Stale data | 25s cache TTL | Wait for next refresh cycle or restart the dashboard |
+
 ---
 
 **Source:** [github.com/Agentoshi/apow-cli](https://github.com/Agentoshi/apow-cli) | **Protocol:** [github.com/Agentoshi/apow-core](https://github.com/Agentoshi/apow-core)