Agent-Wallet

Single-source wallet skill for generate, import, get-balance, sign, and send flows using local wallet files plus executable Node scripts. Use when the user asks for wallet creation, recovery, balance checks, message signing, or transaction sending.

Agent Wallet Skill

Changelog: CHANGELOG.md

Purpose

Use this file as the only wallet skill entrypoint for local wallet workflows.

Runtime Requirements

• Runtime: Node.js 18+
• Required package: viem
• Required secret key: WALLET_SECRET_KEY (used for local secret encryption/decryption)
• Wallet signer file: wallet/signer.json
• Network config file: wallet/config.json

Executable Scripts

Run these scripts from agent-wallet-skills for each action:

• generate-wallet: node scripts/generate-wallet.js --method=<private-key|seed-phrase> [--overwrite=true]
• import-wallet: node scripts/import-wallet.js --seedPhrase="<words>" [--overwrite=true] or --privateKey=0x...
• get-balance: node scripts/get-balance.js --address=0x... [--tokenAddress=0x...] [--decimals=18] [--symbol=TOKEN]
• sign-messages: node scripts/sign-messages.js --message="hello from wallet"
• send (native): node scripts/send.js --to=0x... --amount=<native-amount> --confirm=true [--confirmMainnet=true]
• send (token): node scripts/send.js --to=0x... --amount=<token-amount> --tokenAddress=0x... [--decimals=18] [--symbol=TOKEN] --confirm=true [--confirmMainnet=true]

Notes:

• Wallet material is stored in wallet/signer.json as encrypted fields only.
• Default network is loaded from wallet/config.json with shape [{ rpc_url, chain_id, current }].
• send.js requires explicit --confirm=true.
• Mainnet broadcasts require an additional --confirmMainnet=true.

Routing Logic

1. Identify user intent:
   • create/recover/import wallet -> generate-wallet or import-wallet
   • check native/token balance -> get-balance
   • sign arbitrary payload/message -> sign-messages
   • transfer/broadcast transaction -> send
2. Precheck wallet/config.json for read/write chain operations (get-balance, send, and any network-aware generation flow):
   • require array format [{ rpc_url, chain_id, current }]
   • require exactly one entry with current: true
   • require non-empty rpc_url and chain_id on the current entry
   • if invalid, stop and ask user to set defaults first
3. Execute the script mapped to the action:
   • generate-wallet -> node scripts/generate-wallet.js --method=<private-key|seed-phrase>
   • import-wallet -> node scripts/import-wallet.js --seedPhrase="<words>" or --privateKey=0x...
   • get-balance -> node scripts/get-balance.js --address=0x... [--tokenAddress=0x...]
   • sign-messages -> node scripts/sign-messages.js --message="hello from wallet"
   • send (native) -> node scripts/send.js --to=0x... --amount=<native-amount> --confirm=true [--confirmMainnet=true]
   • send (token) -> node scripts/send.js --to=0x... --amount=<token-amount> --tokenAddress=0x... [--decimals=18] [--symbol=TOKEN] --confirm=true [--confirmMainnet=true]
4. If wallet/signer.json already exists and user asks to regenerate/import over it, require explicit confirmation first.
5. If intent is unclear, ask one focused question:
   • "Do you want to generate/import a wallet, check balance, or send a transaction?"
6. If a script fails, return the error with corrected input guidance.

Generate / Import Workflow

Inputs:

• Seed phrase (12/24 words), or private key (0x prefixed or raw hex), or generation request
• Optional --overwrite=true when replacing existing wallet/signer.json

Rules:

• Default generation method is private-key unless user requests mnemonic.
• Do not overwrite existing signer file unless user requested it and confirmed.
• Validate private key as 64 hex chars (after optional 0x removal).
• Validate seed phrase word count and normalize whitespace.
• Derive address before persisting.
• Encrypt signer secrets before writing to disk.
• Never print full seed phrase/private key in normal responses.

Expected wallet/signer.json structure:

json

{
  "method": "seed_phrase",
  "address": "0x...",
  "encryptedSeedPhrase": "<encrypted-secret>",
  "encryptedPrivateKey": null,
  "createdAt": "2026-04-13T00:00:00.000Z",
  "updatedAt": "2026-04-13T00:00:00.000Z"
}

Balance Workflow

Inputs:

• --address (required)
• --tokenAddress (optional for ERC-20 mode)
• optional --decimals and --symbol

Rules:

• Always validate address and tokenAddress (when provided).
• Always require a valid current network in wallet/config.json.
• Native mode: query getBalance and return raw + formatted values.
• Token mode: query balanceOf; read decimals/symbol when possible, otherwise fall back to defaults.

Send Workflow

Inputs:

• --to recipient (required)
• --amount amount to transfer (required)
• --tokenAddress (optional for ERC-20 mode)
• optional --decimals and --symbol (token mode only)
• --confirm=true (required to broadcast)
• --confirmMainnet=true (required on mainnet chain IDs)

Rules:

• Load signer from wallet/signer.json (seed_phrase or private_key).
• Decrypt signer material with WALLET_SECRET_KEY before deriving account.
• Require valid current network in wallet/config.json.
• Validate recipient address, tokenAddress (when provided), and positive amount.
• Native mode: precheck native balance and send via value transfer.
• Token mode: resolve token decimals/symbol, precheck balanceOf, then call ERC-20 transfer.
• Require explicit broadcast confirmation; require double confirmation for mainnet (--confirmMainnet=true).
• Return tx hash on success, and include transfer mode (native or token).

Sign Workflow

Inputs:

• --message (required)

Rules:

• Load signer from wallet/signer.json (seed_phrase or private_key).
• Decrypt signer material with WALLET_SECRET_KEY before deriving account.
• Require non-empty message content.
• Return deterministic signature and signer address; do not broadcast or require chain config.

Shared Safety Rules

• Never expose full seed phrases/private keys in chat, logs, or summaries.
• Never store plaintext signer secrets in wallet/signer.json.
• Keep wallet files local (wallet/signer.json, wallet/config.json).
• Default to non-broadcast/read-only behavior unless user explicitly asks to send.
• If chain is unspecified, prefer a testnet and state the selection.
• On failure, return actionable correction steps and do not continue automatically.

Failure Handling

• Invalid mnemonic/private key -> stop and request corrected input.
• Missing/invalid wallet/signer.json -> request generate/import first.
• Missing/invalid wallet/config.json -> request default network setup first.
• Multiple or zero current: true entries -> stop and request normalization.
• Insufficient balance for transfer -> return required vs available values.
• RPC timeout/network errors -> retry once, then ask for alternate RPC.

Completion Requirements

Before finishing:

• confirm action executed (generate, import, balance, send)
• confirm secret material was not exposed in plain text
• confirm chain and wallet address used (when applicable)
• provide one next action (backup, verify balance, or track transaction)

Standard Response Contract

Return this structure across all actions:

• action: generate | import | balance | sign | send
• chain: chain id/name used, or none for offline-only generation/import
• 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