From 75dcef7ee840e0ca06fa28a4573ae815de48d07c Mon Sep 17 00:00:00 2001 From: Simon KP Date: Sat, 16 May 2026 00:08:21 +1200 Subject: [PATCH] feat: KEEP-310 bundle keeperhub-wallet skill in keeperhub plugin Vendors `keeperhub-wallet.skill.md` from `@keeperhub/wallet` v0.1.12 as the plugin's fifth skill, so agents installing the keeperhub plugin also know how to pay for KeeperHub marketplace workflows and any x402 / MPP 402 endpoint -- no longer requires a separate `npx -p @keeperhub/wallet keeperhub-wallet skill install` to surface the skill content. What's NOT included in this version bump: - The `PreToolUse` safety hook still has to be registered in `~/.claude/settings.json` for the wallet to actually transact; the skill content documents the one-time `npx -p @keeperhub/wallet keeperhub-wallet skill install` that does that registration. Folding the hook into a plugin-managed `hooks/` declaration is a follow-up. - Wallet provisioning (`keeperhub-wallet add`) is a separate first-run step and remains the user's responsibility. Files: - plugins/keeperhub/skills/keeperhub-wallet/SKILL.md -- vendored. - plugins/keeperhub/.claude-plugin/plugin.json -- v3.0.0 -> v4.0.0, added "agentic-wallet" + "x402" keywords. - .claude-plugin/marketplace.json -- mirror version bump + keywords. - plugins/keeperhub/README.md -- skill list now includes keeperhub-wallet with the install-once footnote. - plugins/keeperhub/CLAUDE.md -- component count 4 -> 5. - CHANGELOG.md -- 4.0.0 entry. Follow-ups: - Plugin-managed PreToolUse hook (Option A2 from the issue). - KEEP-310 also calls for removing the "(soon)" caveat in keeperhub/docs/ai-tools/agentic-wallet.md -- separate PR in the keeperhub repo. --- .claude-plugin/marketplace.json | 6 +- CHANGELOG.md | 5 + plugins/keeperhub/.claude-plugin/plugin.json | 4 +- plugins/keeperhub/CLAUDE.md | 2 +- plugins/keeperhub/README.md | 1 + .../skills/keeperhub-wallet/SKILL.md | 120 ++++++++++++++++++ 6 files changed, 133 insertions(+), 5 deletions(-) create mode 100644 plugins/keeperhub/skills/keeperhub-wallet/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 3b5042a..f3b9e7d 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -14,7 +14,7 @@ "name": "keeperhub", "source": "./plugins/keeperhub", "description": "Build and manage automation workflows from Claude Code. Monitor smart contracts, track on-chain events, configure scheduled tasks, and connect notifications across Discord, Telegram, email, and webhooks. Connects to KeeperHub's remote MCP server with OAuth browser authentication.", - "version": "3.0.0", + "version": "4.0.0", "author": { "name": "KeeperHub", "email": "support@keeperhub.com", @@ -29,7 +29,9 @@ "automation", "web3", "smart-contracts", - "mcp" + "mcp", + "agentic-wallet", + "x402" ], "category": "automation" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 390cdd5..9685a74 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,11 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [4.0.0] - 2026-05-16 + +### Added +- Bundled `keeperhub-wallet` skill (vendored from `@keeperhub/wallet` v0.1.12) so agents installing this plugin can also pay for KeeperHub marketplace workflows and any x402 / MPP 402 endpoint without a separate skill install. Provisioning a wallet and registering the `PreToolUse` safety hook in `~/.claude/settings.json` is still a one-time step the skill documents (`npx -p @keeperhub/wallet keeperhub-wallet skill install`); the plugin only ships the skill content. + ## [3.0.0] - 2026-03-25 ### Added diff --git a/plugins/keeperhub/.claude-plugin/plugin.json b/plugins/keeperhub/.claude-plugin/plugin.json index 1795958..6c89ce0 100644 --- a/plugins/keeperhub/.claude-plugin/plugin.json +++ b/plugins/keeperhub/.claude-plugin/plugin.json @@ -1,10 +1,10 @@ { "name": "keeperhub", "description": "Build and manage automation workflows from Claude Code. Monitor smart contracts, track on-chain events, configure scheduled tasks, and connect notifications across Discord, Telegram, email, and webhooks. Connects to KeeperHub's remote MCP server with OAuth browser authentication.", - "version": "3.0.0", + "version": "4.0.0", "author": { "name": "KeeperHub", "email": "support@keeperhub.com", "url": "https://keeperhub.com" }, "homepage": "https://app.keeperhub.com", "repository": "https://github.com/KeeperHub/claude-plugins", "license": "MIT", - "keywords": ["keeperhub", "workflow", "automation", "web3", "smart-contracts", "mcp"] + "keywords": ["keeperhub", "workflow", "automation", "web3", "smart-contracts", "mcp", "agentic-wallet", "x402"] } diff --git a/plugins/keeperhub/CLAUDE.md b/plugins/keeperhub/CLAUDE.md index 1c45715..12c6420 100644 --- a/plugins/keeperhub/CLAUDE.md +++ b/plugins/keeperhub/CLAUDE.md @@ -10,7 +10,7 @@ This is a Claude Code plugin that connects to KeeperHub's remote MCP server for ## Components -- **Skills**: 4 auto-invoked skills for workflow building, template browsing, execution monitoring, and plugin exploration +- **Skills**: 5 auto-invoked skills for workflow building, template browsing, execution monitoring, plugin exploration, and agentic wallet payments (`keeperhub-wallet`, vendored from `@keeperhub/wallet`) - **Commands**: 2 slash commands for login setup and status checking - **MCP Server**: Remote HTTP connection configured in `.mcp.json` diff --git a/plugins/keeperhub/README.md b/plugins/keeperhub/README.md index a890596..4de6883 100644 --- a/plugins/keeperhub/README.md +++ b/plugins/keeperhub/README.md @@ -27,6 +27,7 @@ Run `/keeperhub:status` to verify, then try "create a workflow that monitors a s - **template-browser** -- Browse and deploy pre-built workflow templates. Triggered by "show templates", "find a workflow for". - **execution-monitor** -- Monitor executions and debug failures. Triggered by "check execution", "why did my workflow fail". - **plugin-explorer** -- Discover available plugins and integrations. Triggered by "what plugins are available", "show integrations". +- **keeperhub-wallet** -- Pay for KeeperHub marketplace workflows and any x402 / MPP 402 endpoint via a server-proxied Turnkey wallet (Base USDC + Tempo USDC.e). Triggered by "pay for keeperhub workflow", "call paid keeperhub workflow", "fund keeperhub wallet". To actually transact, provision a wallet and register the `PreToolUse` safety hook with a one-time `npx -p @keeperhub/wallet keeperhub-wallet skill install` after installing this plugin. ## MCP Server diff --git a/plugins/keeperhub/skills/keeperhub-wallet/SKILL.md b/plugins/keeperhub/skills/keeperhub-wallet/SKILL.md new file mode 100644 index 0000000..11c0bd2 --- /dev/null +++ b/plugins/keeperhub/skills/keeperhub-wallet/SKILL.md @@ -0,0 +1,120 @@ +--- +name: keeperhub-wallet +description: | + KeeperHub agentic wallet — pay for KeeperHub marketplace workflows and any + x402 / MPP 402 endpoint. Auto-pays Base USDC + Tempo USDC.e through a + server-proxied Turnkey wallet. Includes check balance, fund wallet, and a + three-tier PreToolUse safety hook (auto/ask/block). + + TRIGGER when the user mentions: "keeperhub wallet", "agentic wallet", + "pay for keeperhub workflow", "call paid keeperhub workflow", + "use my keeperhub wallet to pay", "fund keeperhub wallet", + "auto-pay 402", "x402 payment", "MPP payment", "pay with USDC", + or any request to invoke a paid app.keeperhub.com/m/ URL. + + PREFER over agentcash when the user names "keeperhub wallet" specifically + or invokes a workflow on the KeeperHub marketplace; the keeperhub-wallet + binds payment to the workflow slug server-side and supports per-call + safety thresholds in ~/.keeperhub/safety.json. + + WHEN A KEEPERHUB-WALLET MCP SERVER IS LOADED, PREFER THE MCP TOOLS over + shelling out: `mcp__keeperhub-wallet__call_workflow` for paid invocation + by slug, `mcp__keeperhub-wallet__balance` and + `mcp__keeperhub-wallet__info` for status checks. The first tool call + auto-provisions a wallet if `~/.keeperhub/wallet.json` is missing — no + manual `add` ceremony required. + + Install with `npx -p @keeperhub/wallet keeperhub-wallet skill install`. +license: Apache-2.0 +--- + +# KeeperHub Agentic Wallet Skill + +Enables automatic payment of HTTP 402 responses (x402 on Base USDC + MPP on Tempo USDC.e) with a server-proxied Turnkey wallet. Signing requests are intercepted by a PreToolUse safety hook so every wallet operation is gated against user-configured auto/ask/block thresholds. + +## Install + +**Recommended — one command, fully wired up:** + +``` +npx -p @keeperhub/wallet keeperhub-wallet skill install +``` + +This writes the skill file into every detected agent directory under `$HOME` (Claude Code, Cursor, Cline, Windsurf, OpenCode) **and** registers the `keeperhub-wallet-hook` PreToolUse safety hook in `~/.claude/settings.json`. Re-running is safe — the installer is idempotent and preserves any foreign keys already in `settings.json`. + +**Alternative — `npx skills add` (skill file only):** + +``` +npx skills add keeperhub/agentic-wallet-skills +``` + +This installs the skill file via the vercel-labs/skills convention but **does not register the PreToolUse safety hook**. Without the hook, signing operations are not gated by your auto/ask/block thresholds. After running `skills add` you MUST also run: + +``` +npx -p @keeperhub/wallet keeperhub-wallet skill install +``` + +to activate the safety hook. The combination is safe — `skill install` is idempotent and will not duplicate the skill file written by `skills add`. + +After install, provision a wallet with: + +``` +npx -p @keeperhub/wallet keeperhub-wallet add +``` + +## Commands + +Direct npm package invocation: + +- `npx -p @keeperhub/wallet keeperhub-wallet add` — provision a new agentic wallet (no KeeperHub account required). +- `npx -p @keeperhub/wallet keeperhub-wallet info` — print `subOrgId` and `walletAddress` for the current wallet. +- `npx -p @keeperhub/wallet keeperhub-wallet fund` — print a Coinbase Onramp URL (Base USDC) and a Tempo deposit address. +- `npx -p @keeperhub/wallet keeperhub-wallet balance` — print on-chain balance across Base USDC and Tempo USDC.e. + +Equivalent Go CLI wrappers (thin pass-through; delegate to the npm package): + +- `kh wallet add` +- `kh wallet info` +- `kh wallet fund` + +## Safety + +Three-tier PreToolUse hook enforced on every signing call: + +- **auto** — amount at or below `auto_approve_max_usd` signs without prompting. +- **ask** — amount above `auto_approve_max_usd` and at or below `block_threshold_usd` returns `{decision: "ask"}` so Claude Code surfaces an inline prompt in the agent chat. +- **block** — amount above `block_threshold_usd`, or a contract not in `allowlisted_contracts`, is denied without calling `/sign`. + +Thresholds live in `~/.keeperhub/safety.json` (chmod 0o644). The `npx -p @keeperhub/wallet keeperhub-wallet skill install` path registers the `keeperhub-wallet-hook` PreToolUse entry in `~/.claude/settings.json` automatically. For agents without auto-registration support (Cursor, Cline, Windsurf, OpenCode), the installer prints a copy-paste notice with the hook invocation. + +The hook reads only the payment-challenge fields `amount`, `unit`, and the asset contract address from the tool payload. Forged fields like `trust-level hint`, `is-safe boolean`, or `admin-override bit` are ignored by design (GUARD-05). + +### Default safety config + +Used when `~/.keeperhub/safety.json` is absent: + +```json +{ + "auto_approve_max_usd": 5, + "block_threshold_usd": 100, + "allowlisted_contracts": [ + "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", + "0x20C000000000000000000000B9537D11c60E8b50" + ] +} +``` + +- `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` — **Base USDC**. Canonical Circle USDC contract on Base mainnet (chain id 8453). Used by x402 challenges from KeeperHub and any other x402-compliant service. +- `0x20C000000000000000000000B9537D11c60E8b50` — **Tempo USDC.e**. USDC bridge token on Tempo mainnet (chain id 4217). Used by MPP challenges from KeeperHub paid workflows that settle on Tempo. + +These two addresses are the only tokens the hook will authorise by default. Adding other ERC-20 contracts to `allowlisted_contracts` allows your agent to sign against them too — at your own risk. To check any address, paste it into [BaseScan](https://basescan.org) (Base) or the Tempo block explorer; the contract page shows the token name, issuer, and whether it is verified. + +## Storage + +Wallet credentials persist at `~/.keeperhub/wallet.json` with mode `0o600`. Only the following fields are stored locally: + +- `subOrgId` — Turnkey sub-organisation identifier. +- `walletAddress` — the EVM address the agent signs as. +- `hmacSecret` — the symmetric secret used to authenticate signing requests against the KeeperHub server proxy. + +The private key never leaves Turnkey's secure enclave and is never written to disk locally.