{"id":"fe908f16-f60b-4936-a3c5-4adae782bdb8","slug":"apow-cli","kind":"skill","name":"apow-cli","summary":"Mining CLI for the APoW protocol on Base — mine AGENT tokens with any local AI agent","owner":"Agentoshi","repoUrl":"https://github.com/Agentoshi/apow-cli","license":"MIT","licenseTier":"permissive","trust":"community","stars":4,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-03-20T02:59:23.000Z","addedAt":"2026-10-21T22:47:05.490Z","logoUrl":"https://avatars.githubusercontent.com/u/190115468?u=3d423516672363688236a50b43a8e02d3e88de69&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["writing"],"tags":[],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-25T15:59:16.711Z","sample":false,"url":"https://conduits.dev/tools/apow-cli","language":"TypeScript","transports":["stdio"],"install":{"npm":"apow-cli"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# APoW CLI\n\nAgent-first mining client for [APoW (Agentic Proof of Work)](https://apow.io) on\nBase. Onboard a Mining Rig, then run the protocol's SMHL and Keccak verification\nflow continuously to earn $AGENT tokens. The contracts are\n[open source](https://github.com/Agentoshi/apow-core).\n\n**Your agent does all the work. You just fund a wallet.**\n\n`apow setup` is agent-first:\n- `Easy Mode`: no config, x402 for RPC + LLM + GPU grinding\n- `Advanced Mode`: choose which credentials you supply and which services stay autonomous\n\n`apow start` is the fastest path: choose Easy or Advanced Mode, complete the\nmandatory Base funding handoff, mint, and mine continuously. Agents can select\nthe same existing Easy Mode directly with `apow start --easy`.\n\n## Install\n\n```bash\nnpm install -g apow-cli\n```\n\nOr run directly:\n\n```bash\nnpx apow-cli\n```\n\n## RPC Setup\n\n> **v0.8.0+: Bring your own RPC or use auto-pay.** You need a Base RPC endpoint. Two options:\n>\n> 1. **Bring your own** (free): Get a free RPC URL from [Alchemy](https://www.alchemy.com/), [QuickNode](https://www.quicknode.com/), or any Base RPC provider. Set `RPC_URL` in your `.env`.\n> 2. **QuickNode x402** (paid, zero setup): Set `USE_X402=true` in your `.env`. Your mining wallet pays for RPC usage via the [x402 payment protocol](https://www.x402.org/). Deposit Base ETH through the funding flow; the CLI converts the initial 2.00 USDC service budget. No API key or account needed.\n>\n> Run `apow setup` to configure interactively.\n\n## For AI Agents\n\nDeposit **Base ETH only**. The CLI quotes the live rig price, retains ETH for gas,\nand converts the service budget to USDC. It tests wallet recovery before giving\nfunding instructions. Rerun the same command after deposit to mint or resume\nan existing rig; the wallet address stays the same.\n\nSee the [assistant profiles](https://apow.io/docs/technical/assistants) for Grok Bot,\nMuse, Instinct, Wajo, OpenClaw, Hermes, Claude Code, Codex, and other runtimes.\nThe [managed cloud service](https://apow.io/docs/technical/managed-mining) is in\ndevelopment; the current CLI still needs a runner.\n\n```bash\nnpx --yes apow-cli@0.12.3 start --easy\n```\n\nRelevant Easy Mode settings include:\n\n```bash\nKEYSTORE_PATH=~/.apow/keystores/wallet-0x....json\nUSE_X402=true\nUSE_X402_GRIND=true\nLLM_PROVIDER=clawrouter\nALLOW_LOCAL_FALLBACK_WITH_X402=false\n```\n\nThe keystore password is prompted interactively. For headless launch services,\nsave a `KEYSTORE_PASSWORD_CMD` reference in the private `.env` and use a supported\nsecret manager. Run `apow wallet verify-recovery` before funding. A password kept\nonly in process memory cannot recover after a restart. Never send secrets in chat.\nNever put it in chat or commit it to a project file. See [skill.md](skill.md) for\nthe narrow autonomous mining workflow.\n\n## For Humans\n\nIf you prefer to do it yourself:\n\n```bash\nnpx apow-cli start   # guided happy path: setup -> funding checks -> mint -> mine\n```\n\nIf you want to control each step manually, the older step-by-step flow is still supported below.\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `apow start [--easy]` | Existing Easy/Advanced flow: setup -> Base funding check/handoff -> mint -> mine |\n| `apow setup` | Agent-first setup wizard: Easy Mode (x402 everywhere) or Advanced Mode |\n| `apow fund` | ETH-only funding quote, conversion, and configured bridge routes |\n| `apow wallet new` | Generate a new encrypted mining wallet |\n| `apow wallet verify-recovery` | Test fresh-process unlock before funding |\n| `apow wallet list` | List every wallet generated locally by this APoW CLI and mark the active wallet |\n| `apow wallet use [address-or-number]` | Select a generated wallet for the current project (`select` is an alias) |\n| `apow wallet show` | Show configured wallet address |\n| `apow wallet backup` | Show the encrypted keystore backup location; never display wallet secrets |\n| `apow wallet migrate` | Encrypt legacy `PRIVATE_KEY` into a keystore and clear `.env` |\n| `apow wallet payout set <addr>` | Configure a cold payout address for AGENT sweeps |\n| `apow wallet sweep [--all]` | Sweep mined AGENT, and optionally excess ETH/USDC, to payout |\n| `apow wallet fund <addr> [eth]` | Send ETH to another address (default: mint price + gas) |\n| `apow policy show/init/set mode` | Inspect or change local signing policy |\n| `apow mint` | Confirm and mint a MiningAgent NFT (one per wallet) |\n| `apow mine [tokenId]` | Mine $AGENT continuously (auto-detects best rig) |\n| `apow stats [tokenId]` | View mining stats |\n| `apow dashboard start` | Launch the local APoW-wallet dashboard |\n| `apow dashboard wallets` | List wallets generated locally by this CLI |\n\n## Configuration\n\nCreate a `.env` file or use `apow setup`:\n\n```bash\nKEYSTORE_PATH=~/.apow/keystores/wallet-0x....json  # Preferred: encrypted wallet JSON\nUSE_X402=true                  # Auto-pay RPC + LLM via x402 (2.00 USDC minimum starting balance, no API keys)\nUSE_X402_GRIND=true            # Auto-pay remote GPU grinding via x402\nALLOW_LOCAL_FALLBACK_WITH_X402=false  # Easy Mode default: do not burn local CPU while x402 GPU is active\n# STALE_CHECK_INTERVAL=5       # Seconds between stale-challenge checks while grinding (default: 5)\n# RPC_URL=https://...          # Or: bring your own RPC (free from Alchemy, QuickNode, etc.)\n# LLM_PROVIDER=clawrouter     # x402: clawrouter | API key: openai/anthropic/gemini/deepseek/qwen | local/subscription CLI: ollama/claude-code/codex\n# LLM_MODEL=...              # Optional override; x402 selects automatically\n# LLM_API_KEY=sk-...          # Required only for API-key providers\n# KEYSTORE_PASSWORD=          # Temporary unlock only; never store the password here\n# KEYSTORE_PASSWORD_CMD=...   # Preferred headless unlock command, stdout is used as password\n# APOW_POLICY=enforce         # enforce | warn | off\n# APOW_PAYOUT_ADDRESS=0x...   # optional cold payout wallet for AGENT sweeps\n# Bridging (only for `apow fund`)\n# SOLANA_RPC_URL=https://api.mainnet-beta.solana.com\n# ETHEREUM_RPC_URL=https://cloudflare-eth.com\n# SQUID_INTEGRATOR_ID=          # free, get at squidrouter.com\n# Contract addresses (defaults built-in, override only if needed)\n# MINING_AGENT_ADDRESS=0xB7caD3ca5F2BD8aEC2Eb67d6E8D448099B3bC03D\n# AGENT_COIN_ADDRESS=0x12577CF0D8a07363224D6909c54C056A183e13b3\n```\n\nSee [.env.example](.env.example) for all options.\n\n## Wallet Protocol v2\n\nMining requires a hot EOA because the immutable APoW contracts require direct wallet signatures. Wallet Protocol v2 limits that hot wallet's blast radius:\n\n- every transaction and x402 typed-data signature goes through a local policy guard;\n- mined AGENT can be swept to a separate payout address with `apow wallet payout set <addr>` — AGENT transfers are frozen on-chain until the LP pool deploys, so the CLI skips AGENT sweeps until `lpDeployed` flips and then activates them automatically (ETH/USDC sweeps via `--all` work immediately);\n- audit and spend ledgers are written under `~/.apow/audit-<address>.jsonl` and `~/.apow/spend-<address>.jsonl`;\n- child grinder and local LLM processes do not receive wallet or keystore-password secrets;\n- generated wallets are written only as encrypted keystores, and wallet commands never print or write a raw-key export;\n- Easy Mode refuses to run if the enforce-mode mint or x402 policy caps were relaxed beyond its defaults;\n- `apow start --easy` selects the existing Easy Mode without adding a second approval or wallet-control system.\n\nUseful commands:\n\n```bash\napow policy show\napow wallet payout set 0x...\napow wallet sweep\napow wallet migrate            # convert legacy PRIVATE_KEY to KEYSTORE_PATH\n```\n\nFor headless unlocks, prefer a command that prints the password from your OS secret store:\n\n```bash\nKEYSTORE_PASSWORD_CMD=\"security find-generic-password -s apow-keystore -w\"\n```\n\n## LLM Providers (for Minting)\n\nAn LLM is required when minting a new Mining Rig NFT because the mint gate uses a\n20-second SMHL challenge. Easy Mode handles SMHL and mining automatically after\nthe user funds the dedicated wallet.\n\nAdvanced Step 3 groups the choices by payment and execution model:\n\n1. **Auto** — Zero Config via x402. The model is selected automatically and each\n   request is paid from the mining wallet's Base USDC balance.\n2. **API key** — OpenAI, Anthropic, Gemini, DeepSeek, or Qwen.\n3. **Local / subscription CLI** — Ollama runs inference on the user's machine;\n   Claude Code and Codex run local command-line clients but use hosted models and\n   the user's existing subscription allowance.\n\n| Provider | Default model | Billing | Notes |\n|----------|---------------|---------|-------|\n| Auto via x402 | Automatic | Wallet-paid USDC | Zero Config; no API key or model selection required |\n| OpenAI | `gpt-4o-mini` | ~$0.001 | Cheapest API key option, fast |\n| Gemini | `gemini-2.5-flash` | ~$0.001 | Fast, good accuracy |\n| DeepSeek | `deepseek-chat` | ~$0.001 | Fast, accessible in China |\n| Qwen | `qwen-plus` | ~$0.002 | Alibaba Cloud |\n| Anthropic | `claude-sonnet-4-5-20250929` | ~$0.005 | Works but slower |\n| Ollama | `llama3.1` | Local compute | Truly local inference; Ollama must be running with the model installed |\n| Claude Code | `haiku` | Claude subscription allowance | Hosted inference through an installed, signed-in CLI |\n| Codex | `gpt-5.6-luna` | ChatGPT subscription allowance | Hosted inference through an installed, signed-in CLI |\n\nPrepare one of the local/subscription choices before minting:\n\n```bash\nollama pull llama3.1   # Ollama only; keep the Ollama service running\nclaude login           # Claude Code; sign in with the intended Claude subscription\ncodex login            # Codex; choose ChatGPT subscription access\n```\n\nAPoW disables Claude Code tools and session persistence. It runs Codex from an\nisolated temporary directory in ephemeral, read-only mode. Both child processes\nreceive a strict environment allowlist rather than wallet secrets or API-billing\nkeys. Both subscription adapters passed off-chain SMHL command tests; neither is\nyet recorded as a completed APoW mainnet mint.\n\n## Funding (v0.7.0+)\n\nSend **one asset: Base ETH**. `apow start --easy` quotes the current rig price,\na conservative 0.003 ETH reserve, swap gas, and the missing 2 USDC service budget.\nThe reserve is not the actual gas cost per mine. The Uniswap quote includes a\n2% input buffer and requires enough USDC output; the CLI checks balances again\nafter the swap. The fee budget uses current L2 fee caps, a fixed transaction gas\nceiling, and buffered Base L1/operator fees. Those L2 caps are used when signing.\nIt stops if conversion would consume the required ETH reserve.\n\n```bash\napow start --easy                       # quote, deposit ETH, then rerun to convert/mint/mine\napow fund                              # default Base ETH; resumes existing deposits\napow fund --chain solana --token sol    # configured Squid route: SOL to Base ETH\napow fund --chain solana --token usdc   # configured Squid route: USDC to Base ETH\napow fund --chain ethereum --token eth\napow fund --no-swap                     # quote only; no conversion\n```\n\nSolana routes require an operator-configured `SQUID_INTEGRATOR_ID`. They are\nunavailable until configured. Bridge quotes must cover the Base requirement\nafter fees and slippage before a deposit address is offered. Do not send SOL\nto the Base wallet address. Keep the bridge request ID and respect its expiry.\n\nExisting USDC stays usable for services. Base ETH is the funding deposit asset;\nthe CLI does not ask the user to supply both ETH and USDC.\n\n## x402 GPU Grinding\n\nNo GPU? No problem. Remote RTX 4090 nonce grinding via the [x402 payment protocol](https://www.x402.org/) — ~$0.006/grind (dynamic pricing tracks actual GPU cost), zero setup:\n\n```bash\n# In your .env (enabled automatically in Easy Mode)\nUSE_X402_GRIND=true\n# ALLOW_LOCAL_FALLBACK_WITH_X402=true   # Advanced Mode hybrid option\n```\n\nIn Easy Mode, the HTTP grinder is the only nonce source, so agents do not silently burn local CPU while remote x402 GPU mining is active. Advanced Mode can opt into a hybrid local fallback. Front-running is cryptographically impossible — nonces are bound to `keccak256(challenge, msg.sender, nonce)`.\n\n| Config | Description |\n|--------|-------------|\n| `USE_X402_GRIND` | Enable remote GPU grinding (default: same as `USE_X402`) |\n| `ALLOW_LOCAL_FALLBACK_WITH_X402` | Let local JS fallback run alongside x402 GPU (`false` in Easy Mode) |\n| `GRIND_URL` | Custom GrindProxy endpoint (default: `https://grind.apow.io/grind`) |\n\nSelf-host your own GrindProxy: see [apow-grind](https://github.com/Agentoshi/apow-grind).\n\n## GPU Mining (v0.9.2+)\n\nThe miner auto-detects native GPU and CPU grinder binaries for dramatically faster nonce grinding. Source files ship with the npm package — run `apow build-grinders` to compile and install to `~/.apow/`:\n\n```bash\nnpx apow-cli build-grinders              # auto-detects compilers + GPU arch\nnpx apow-cli build-grinders --cuda-arch sm_89  # override CUDA architecture\n```\n\n| Grinder | Platform | Speed | Requirements |\n|---------|----------|-------|--------------|\n| Metal GPU | macOS (Apple Silicon) | ~260-500 MH/s | Xcode CLI tools (`clang`) |\n| CUDA | NVIDIA GPU | ~20 GH/s | CUDA toolkit (`nvcc`) |\n| CPU-C | Any (multi-threaded C) | ~150-300 MH/s | `clang` or `gcc` |\n| JS (fallback) | Any (worker_threads) | ~2-5 MH/s | Built-in, no setup |\n\nAll available grinders race in parallel — first valid nonce wins. Falls back to JS automatically if no native binaries are found.\n\n### Remote GPU Setup (Vast.ai)\n\n```bash\n./local/vast-setup.sh    # rent RTX 4090, upload + compile CUDA grinder\n```\n\nThen add to `.env`:\n```\nVAST_IP=<ip>\nVAST_PORT=<port>\n```\n\nThe CUDA grinder runs over SSH alongside your local Metal/CPU grinders — genuinely additive hash power.\n\n### Other Optimizations\n\n- **Faster stale restarts**: The miner re-checks the challenge every 5 seconds by default and aborts dead work quickly across local, native GPU/CPU, and x402 grinding.\n- **JS threads**: If no native grinders are found, falls back to `worker_threads` across all CPU cores. Set `MINER_THREADS` in `.env` to override.\n\n## Dashboard\n\nMonitor wallets generated locally by this APoW CLI from a single web UI. Zero external dependencies -- vanilla HTML/JS served by the CLI on `127.0.0.1` only. The dashboard does not scan directories, ingest wallet files, accept manually added addresses, or load external fleet configurations. It loads once, then only refreshes chain data when you click **Refresh**, so it does not burn RPC quota in the background.\n\n```bash\n# Quick start: generate an encrypted wallet and launch\napow wallet new\napow dashboard start           # open http://localhost:3847\n```\n\n### Commands\n\n| Command | Description |\n|---------|-------------|\n| `apow dashboard start` | Launch dashboard web UI |\n| `apow dashboard wallets` | List wallets generated locally by this CLI |\n\n### Wallet Scope\n\n`~/.apow/generated-wallets.json` records only addresses and encrypted-keystore paths created by `apow wallet new` or the setup wizard's new-wallet flow. A wallet appears only while its matching keystore exists under `~/.apow/keystores/`. Imported wallets, arbitrary addresses, legacy plaintext files, and unrelated filesystem artifacts are intentionally excluded.\n\nRefreshes use chunked multicalls and a 25-second cache. Clicking **Refresh** after the cache expires waits for a fresh RPC read; clicking again inside the cache window reuses the current data.\n\n## Protocol\n\nThe APoW protocol contracts and documentation live in [apow-core](https://github.com/Agentoshi/apow-core).\n\n## License\n\nMIT\n"}