moltbank

# MoltBank Skill For AI Agents Use MoltBank for: - authentication pairing - treasury balance reads - pending approval reads - payment drafting - x402 discovery and one-shot auto-pay actions ## Preferred Execution Order 1. If MCP tools are available, use MCP first. 2. If MCP tools are unavailable, discover exact CLI contract first: - `moltbank tools list --json` - `moltbank schema --json` - `moltbank schema <command> --json` - or command `--help` 3. Execute CLI commands with `--json`. ## Hard Rule Do not guess flags, argument names, or tool input shapes from memory. Always discover exact usage on demand from MCP tool schemas or CLI schema/help. When using `moltbank schema --json`, use command `name` for CLI execution. Do not execute `id` values (for example `moltbank_*`) as terminal commands. When the user asks "what tools/functions can I use", run `moltbank tools list --json` and answer from that output. ## Join / Bootstrap Sequence When the user asks to "join MoltBank" or to follow setup instructions: Runtime isolation rule: - Do not use another runtime's skill manager (for example OpenClaw) to verify or install the skill for the current runtime. Each runtime is independent. 1. Use only the current runtime's native skill mechanism: - If current runtime is OpenClaw: run `openclaw skills list` - If current runtime is skills.sh-compatible (for example Claude Code, Codex, Hermes, or Manus when `npx skills` is available): run `npx skills ls` - If runtime capability is unclear, ask the user which runtime should be configured before running any skill-manager command. 2. Treat the skill as installed only when the current runtime reports it as ready/active. 3. If the skill is missing or not ready, and the user explicitly approves setup, use the current runtime's installer: - OpenClaw example: `openclaw skills install moltbank`, then confirm with `openclaw skills list` (`moltbank` must be `✓ ready`) - skills.sh example (including Claude Code, Codex, Hermes, or Manus when compatible): `npx skills add moltbankhq/moltbank-skill` 4. Check CLI availability with `moltbank --version`. 5. If CLI is missing and the user explicitly approves setup, install the CLI: - `npm install -g @moltbankhq/cli` 6. Continue auth flow (`moltbank auth begin --json` then `moltbank auth poll --json` after user approval). 7. Verify final state with `moltbank whoami --json`. 8. If you run `moltbank doctor --json` and it fails, report exact failing checks; do not claim "all good". 9. During basic join/setup, do not run x402 signer initialization or wallet registration unless the user explicitly requests x402 setup or a requested command requires it. Never claim "skill installed", "setup complete", or "everything is ready" without command evidence from the current session. # Authentication (Chat-Driven Flow) If credentials are missing or unauthorized, prefer completing login through chat guidance. Use this recommended chat flow: 1. Run `moltbank auth begin --json`. 2. Extract `verification_uri_complete` and `user_code` from the JSON output. 3. Present the approval URL to the user in the chat and tell them to verify the domain is `app.moltbank.bot` before opening it. 4. Ask the user to click the link, approve the connection in their browser, and reply `done`. 5. When the user replies `done`, run `moltbank auth poll --json`. 6. If the command returns `AUTH_PENDING`, politely tell the user the approval is still pending and ask them to confirm they completed the browser flow. 7. If the command succeeds, continue with the user’s original request. Do not rely on model memory to remember the device code. The CLI manages pending auth state locally. Never execute long-running interactive authentication wrappers as an agent tool. ## x402 Payments When the user asks to buy or use an x402-protected endpoint: 1. If the exact x402 URL is known, use `moltbank_x402_auto_pay`. 2. If the URL is not known, use `moltbank_discover_x402_bazaar` first, then use `moltbank_x402_auto_pay`. 3. Do not manually orchestrate signer init, wallet registration, inspect, treasury funding, payment execution, or receipt logging. `moltbank_x402_auto_pay` handles those steps. 4. If auto-pay returns `status: needs_user_approval`, explain that clearly and stop. If `bootstrapBudget.approvalUrl` is present, provide that exact link and tell the user to approve it, then rerun the same auto-pay request. 5. If auto-pay returns `status: needs_configuration`, explain what setup is missing and stop. 6. If auto-pay succeeds, report success and include the returned `paymentTxHash` when available. 7. If auto-pay returns a bootstrapBudget.approvalUrl, present that exact link to the user and tell them to approve it to grant the bot the necessary permissions. Once they approve it, rerun the exact same auto-pay command. ## Budget Proposals On Base (Important) When creating a Base bot budget (`propose_bot_budget` / `moltbank budget propose`) and the backend says the x402 wallet is not registered: 1. Run `moltbank x402 signer init --json` to obtain/reuse the bot wallet address. 2. Run `moltbank x402 wallet register --wallet-address "<signerAddress>" --json`. 3. Retry the original budget proposal exactly once. 4. If it still fails, stop and report the blocker to the user with the exact error. Do not enter retry loops. Never repeat the same failing command more than 2 times without new inputs or state changes. For raw fallback calls, `moltbank mcp call` supports: - `--arg key=value` (repeatable) - `--body '{"key":"value"}'` (JSON object for tool arguments) ## Export History Delivery `export_transaction_history` supports delivery channels: - `slack` (default for Slack context) - `telegram` (requires `telegramChatId`) - `inline` (returns file payload in tool response; default for non-Slack contexts) CLI flags: - `--delivery-channel slack|telegram|inline` - `--telegram-chat-id <id>` (required when channel is telegram) - `--slack-user-id <id>` (optional for Slack delivery outside Slack context) ## Dependency Setup (Only With Explicit User Approval) MoltBank usage depends on: - a skill installation in the host runtime - the local `moltbank` CLI MoltBank usage requires two separate dependencies: 1. The skill installed in the host runtime (e.g., via `npx skills add` ) 2. The local `moltbank` CLI Do not skip the runtime skill installation just because the local CLI is already installed. If setup is needed and the user explicitly approves installation: - do not invent ad-hoc install commands - do not use one runtime's manager to infer another runtime's skill installation status - treat skill installation as satisfied only when the runtime reports the skill as ready/active - if bootstrapping another runtime, install the skill first: - OpenClaw: `openclaw skills install moltbank` - skills.sh-compatible runtimes: `npx skills add moltbankhq/moltbank-skill` - then install the CLI: - `npm install -g @moltbankhq/cli` - validate after installation: - `moltbank auth begin --json` - `moltbank doctor --json` Never auto-install dependencies without user approval. ## Boundaries - Do not edit global runtime configuration. - Do not mutate sandbox defaults. - Do not install this skill or the `moltbank` CLI unless the user explicitly approves it. - Do not invent custom install commands when a platform-declared install flow exists. - Do not state that setup succeeded unless command output in this session confirms it. - Keep secrets local; never print full tokens, access tokens, or private keys.