ClawHub

Agent-Wallet

Workflows

Route wallet workflows for agents that need to generate or import wallets using either a seed phrase or private key. Use when the user asks for wallet creation, import, recovery, or key-based onboarding.

Install

openclaw skills install agent-wallets

Agent Wallet Skills

Purpose

Use this skill as the main entrypoint for wallet setup workflows.

Runtime Requirements

  • Runtime: Node.js 18+ (or equivalent TS/JS runtime)
  • Required package: viem
  • Network access: RPC endpoint for the target chain
  • Secret storage: vault, key manager, or encrypted secret store

Required Secrets / Inputs

  • RPC_URL for chain reads/writes
  • SEED_PHRASE only when user explicitly chooses mnemonic import/signing
  • PRIVATE_KEY only when user explicitly chooses private key import/signing
  • Agent must ask for confirmation before reading env-based secrets

Wallet Type -> Skill Location Map

Routing Logic

  1. Check if the agent already has a wallet configured:
    • if wallet exists, use existing wallet flow
    • if wallet does not exist, run wallet generation flow (step 2)
  2. Wallet generation flow (no existing wallet):
    • ask preferred method: seed phrase or private key import
    • if user does not provide a method, default to generating a new seed phrase wallet
    • generate/import with viem account helpers in local-wallet/SKILL.md
    • derive address/public key and persist via the project's secure secret mechanism
  3. Identify the wallet input type from the user request:
    • mnemonic / seed phrase words
    • hex private key string
    • request to generate a new wallet
  4. Route by wallet type to the mapped location:
    • seed phrase -> local-wallet/SKILL.md
    • private key -> local-wallet/SKILL.md
    • check balance -> local-wallet/balance/SKILL.md
    • send transaction -> local-wallet/send/SKILL.md
  5. If input type is unclear, ask one focused question:
    • "Do you want to use a seed phrase or a private key?"

No Wallet Exists (Viem Flow)

When the agent has no wallet configured, create one with viem before continuing.

Preferred default (generate new private key wallet)

import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'

const privateKey = generatePrivateKey()
const account = privateKeyToAccount(privateKey)

// Persist privateKey via secure secret storage only (env vault, key manager, etc.)
// Use account.address as the agent wallet address.

Optional seed phrase path

  • If user explicitly asks for seed phrase-based setup, follow local-wallet/SKILL.md seed phrase flow.
  • Derive the account/address and store secret material in secure secret storage.

Required checks after generation

  • Wallet address exists and is valid format for the target chain.
  • Secret material is stored securely and never echoed in plaintext.
  • Agent metadata references the new wallet address for future operations.

Shared Safety Rules

  • Never print full seed phrases or private keys in outputs, logs, or summaries.
  • Mask secrets when showing examples (for example ab12...9f).
  • Prefer offline generation/import steps where possible.
  • Remind users to back up secrets in a secure location.
  • Default to read-only actions until user explicitly asks to send/broadcast.
  • If chain is not provided, default to a testnet and state that choice.
  • Never broadcast immediately after simulation without explicit confirmation.

Completion Requirements

Before finishing:

  • confirm wallet address/public key was derived successfully
  • confirm secret material was not exposed in plain text
  • if wallet was missing, confirm a new wallet was created and stored securely
  • provide next action (backup, test transaction, or network config)

Standard Response Contract

Return this structure across all wallet skills:

  • action: generate | import | balance | send
  • chain: chain id/name used
  • address: active wallet or queried address
  • txHash: transaction hash when available, else null
  • status: success | failed | needs_confirmation
  • next_step: one clear follow-up action
More in Workflows