keeperhub-ai-tools-agentic-wallet

Files (1)

• SKILL.md

SKILL.md (first lines)

# Agentic Wallets

## Overview
Documentation for Agentic Wallets integration and usage within the KeeperHub ecosystem.

[AI Tools](https://docs.keeperhub.com/ai-tools)

KeeperHub paid workflows settle via [x402](https://docs.cdp.coinbase.com/x402) on Base USDC or MPP on Tempo USDC.e: each call carries a USDC payment, and the server returns a result only after the payment is verified. To call a paid workflow, your agent needs an x402/MPP wallet.
This page covers the first-party KeeperHub agentic wallet (skill + npm package, server-side Turnkey custody) and the main third-party alternatives. Every wallet listed works with KeeperHub and with any other x402/MPP-compliant service.

A skill + npm package from KeeperHub. Custody is server-side in a per-wallet [Turnkey sub-organisation](https://docs.turnkey.com/concepts/sub-organizations), so no private key lands on disk. A PreToolUse hook gates every signing call against a three-tier (auto / ask / block) policy sourced from ~/.keeperhub/safety.json.

`PreToolUse`

`~/.keeperhub/safety.json`

### Install
Two steps: register the skill + safety hook, then provision a wallet. Run the commands yourself, or have your agent do it for you.
Manual:

`npx -p @keeperhub/wallet keeperhub-wallet skill install npx -p @keeperhub/wallet keeperhub-wallet add`

`npx -p @keeperhub/wallet keeperhub-wallet skill install npx -p @keeperhub/wallet keeperhub-wallet add`

Have your agent do it: paste this prompt:
Install the KeeperHub agentic wallet: run npx -p @keeperhub/wallet keeperhub-wallet skill install to register the skill and safety hook, then npx -p @keeperhub/wallet keeperhub-wallet add to provision a new wallet. Report the subOrgId and wallet address when done.

`npx -p @keeperhub/wallet keeperhub-wallet skill install`

`npx -p @keeperhub/wallet keeperhub-wallet add`

The install step writes the skill file into every detected agent skill directory (Claude Code, Cursor, Cline, Windsurf, OpenCode) and registers the keeperhub-wallet-hook PreToolUse safety hook in ~/.claude/settings.json. The add step provisions a fresh Turnkey sub-organisation and writes ~/.keeperhub/wallet.json (mode 0600). The file contains only your sub-org identifier, your EVM wallet address, and an HMAC shared secret used to authenticate signing requests against KeeperHub — no private key. The signing key material is generated inside [Turnkey’s secure enclave](https://docs.turnkey.com/concepts/overview#the-system-level-threat-model-we-solve) and never leaves it; nothing in wallet.json alone is enough to sign a transaction.

`keeperhub-wallet-hook`

`PreToolUse`

`~/.claude/settings.json`

`add`

`~/.keeperhub/wallet.json`

`0600`

`wallet.json`

Restart your agent session once after this so it picks up the newly installed skill.

### First payment
The wallet handles payment; the agent still needs a way to discover and call KeeperHub workflows. That comes from the [KeeperHub [MCP server](https://docs.keeperhub.com/ai-tools/mcp-server)](https://docs.keeperhub.com/ai-tools/mcp-server), which exposes the search_workflows and call_workflow meta-tools to your agent. You can install the MCP server on its own (see the MCP server page) or bundled with the [KeeperHub Claude Code plugin](https://docs.keeperhub.com/ai-tools/claude-code-plugin), which wires both the MCP server and (soon) the wallet skill in one step.

`search_workflows`

`call_workflow`

With MCP + wallet both installed, ask your agent in plain language:
Use KeeperHub to check the ETH balance of 0xC300B53616532FDB0116bcE916c9307377362B51.

`0xC300B53616532FDB0116bcE916c9307377362B51`

Run the KeeperHub mcp-test workflow for 0xC300....

`mcp-test`

`0xC300...`

The agent discovers available workflows at runtime through the KeeperHub meta-tools (search_workflows + call_workflow) and picks the best match. When a paid workflow returns a 402, the wallet intercepts the challenge, signs through the server-side proxy (x402 on Base USDC or MPP on Tempo USDC.e), and the call retries transparently. Most KeeperHub paid workflows accept both protocols; today the wallet pays via x402 by default and uses MPP when the workflow is MPP-only. If the amount exceeds your auto_approve_max_usd the safety hook surfaces an inline permission prompt before any payment is authorised.

`search_workflows`

`call_workflow`

`402`

`auto_approve_max_usd`

### Safety hooks
Every wallet signing call is gated by a PreToolUse hook that reads thresholds from ~/.keeperhub/safety.json (never from the transaction payload):

`PreToolUse`

`~/.keeperhub/safety.json`

`auto_approve_max_usd`

`auto_approve_max_usd`

`block_threshold_usd`

`{decision: "ask"}`

`block_threshold_usd`

`allowlisted_contracts`

`/sign`

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 or admin-override are ignored by design.

`amount`

`unit`

`trust-level hint`

`admin-override`

### Server-side hard limits
Beyond the client-side hook, a set of Turnkey-enforced policies apply to every wallet and cannot be bypassed by editing safety.json or changing the agent’s hook. They are created per sub-organisation at provision time and enforced by Turnkey itself on every signing activity:

`safety.json`

- Contract allowlist. Signing is denied on any call whose target contract is not Base USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913) or Tempo USDC.e (0x20C000000000000000000000B9537D11c60E8b50). On the EIP-712 (x402) signing path the same restriction is applied against the typed-data domain’s verifying contract.
- Per-transfer cap. transfer() or transferFrom() of more than 100 USDC is denied. The same 100 USDC ceiling applies to EIP-3009 TransferWithAuthorization typed-data signing.
- Approval cap. approve() above 100 USDC is denied. Anything over the same 100 USDC per-transfer ceiling is rejected.
- Chain allowlist. EIP-712 signing is denied for any domain.chainId outside Base (8453), Tempo mainnet (4217), and Tempo testnet (42431).
- Daily spend cap. Aggregate signed payments per wallet are bounded at 200 USDC per UTC day by default. Requests that would exceed the cap return 429 DAILY_CAP_EXCEEDED with a Retry-After header counting down to the next UTC midnight. The cap protects against a compromised HMAC secret being used to drain the wallet faster than an operator can notice and rotate. If a legitimate workflow needs a higher cap, contact KeeperHub support.

From nickthelegend/keeperhub-skills, MIT.

More from nickthelegend/keeperhub-skills