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=\x3Cprivate-key|seed-phrase> [--overwrite=true]
• import-wallet: node scripts/import-wallet.js --seedPhrase="\x3Cwords>" [--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=\x3Cnative-amount> --confirm=true [--confirmMainnet=true]
• send (token): node scripts/send.js --to=0x... --amount=\x3Ctoken-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=\x3Cprivate-key|seed-phrase>
   • import-wallet -> node scripts/import-wallet.js --seedPhrase="\x3Cwords>" 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=\x3Cnative-amount> --confirm=true [--confirmMainnet=true]
   • send (token) -> node scripts/send.js --to=0x... --amount=\x3Ctoken-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:

{
  "method": "seed_phrase",
  "address": "0x...",
  "encryptedSeedPhrase": "\x3Cencrypted-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