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