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 a...

Security Scan

The skill's code and instructions are generally coherent for a local file-based wallet, but there are metadata and packaging inconsistencies (declared env vs registry metadata, missing install guidance for the viem dependency) that need clarification before use.

Purpose & Capability

Name/description (local wallet: generate/import/balance/sign/send) match the scripts and file-based workflows. WALLET_SECRET_KEY is logically required for encrypting/decrypting local signer material.

Instruction Scope

SKILL.md is explicit about actions, file paths (wallet/signer.json, wallet/config.json), confirmation gates (overwrite, mainnet double confirmation), and avoids printing raw secrets. The runtime instructions limit activity to wallet generation, signing, balance checks, and sending via configured RPCs.

Install Mechanism

No install spec is provided even though SKILL.md declares a runtime dependency on Node >=18 and the 'viem' package. The bundle includes Node scripts but provides no guidance to ensure 'viem' is installed — this is an operational gap (not necessarily malicious) that can cause failures or unexpected behavior if the runtime differs from the developer's environment.

Credentials

The scripts legitimately require WALLET_SECRET_KEY (used by secret-crypto.js to derive the AES key). However, the registry metadata supplied earlier lists 'Required env vars: none' while the SKILL.md frontmatter and code require WALLET_SECRET_KEY — an inconsistency that should be resolved before trusting the skill.

Persistence & Privilege

The skill does not request elevated privileges or permanent always: true presence. It reads/writes only its own wallet files under 'wallet/'. It does rely on the agent being able to run the included Node scripts (normal for a code-backed skill).

What to consider before installing

This skill appears to be a legitimate local wallet tool, but there are a few things to check before installing or using it: - Confirm the WALLET_SECRET_KEY requirement: SKILL.md and the code require WALLET_SECRET_KEY (used to encrypt/decrypt wallet material). The registry metadata showing no required env var is contradictory — ask the publisher to fix the metadata or document why it's missing. - Ensure your environment has Node 18+ and the 'viem' dependency installed; the skill provides scripts but no install instructions for dependencies. Run in an isolated environment if you can. - Protect WALLET_SECRET_KEY: treat it as a high-value secret (store in a secure vault/OS keychain) because possession allows decrypting local signer files and signing/sending transactions. - Review wallet/config.json RPC URLs before use. RPC endpoints are necessary but can be malicious or log requests — use trusted RPCs and test on a non‑mainnet chain first. - Backup wallet/signer.json and test generate/import/get-balance flows on testnets before broadcasting any mainnet transaction. The skill enforces confirmations, but human verification is still recommended. If the author can correct the registry metadata and add installation guidance for dependencies, that will remove the main inconsistencies flagged here.

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:

{
  "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