Skip to main content

Wallet Guide

This guide covers wallet management, transactions, and cycles in AgentVault.

Overview​

AgentVault supports multi-chain wallets:

  • ICP (Internet Computer) - Primary wallet for canister operations
  • Polkadot - For cross-chain transactions
  • Solana - For DeFi and DApp interactions

Wallet Types​

Local Wallet​

Encrypted wallet stored locally on disk:

# Create local wallet
agentvault wallet create

# Features:
# - Encrypted storage (AES-256)
# - Hardware wallet compatibility
# - Multiple accounts support

Hardware Wallet​

Generate a wallet's key on a Ledger device (or in an Intel SGX enclave):

# The private key stays on the device; AgentVault stores the public key and address
agentvault wallet create --chain cketh --agent-id my-agent --hsm ledger

wallet sign does not use the device yet. It needs a private key on disk, so it cannot sign for a hardware wallet.

Creating Wallets​

ICP Wallet​

# Create new ICP wallet
agentvault wallet create --network icp

# Output: Wallet ID and principal

Importing Wallet​

Import existing wallet from mnemonic or private key:

# Import from mnemonic
agentvault wallet import --mnemonic

# Import from private key
agentvault wallet import --private-key

Wallet Commands​

List Wallets​

View all connected wallets:

agentvault wallet list

Wallet Balance​

Check wallet balance:

# Check all wallets
agentvault wallet balance

# Check specific wallet
agentvault wallet balance <wallet-id>

Sign Transaction​

Sign a transfer with one of an agent's wallets:

# Interactive: pick a wallet, then enter the recipient and amount
agentvault wallet sign --agent-id <agent-id>

wallet sign signs ckETH, Solana and Polkadot transfers with the wallet's own key, prints the signed transaction and offers to save it under .agentvault/signed-txs/ in the current folder. It does not broadcast it. Signing is not implemented for ICP and Arweave wallets: for those the command fails and saves nothing.

Transaction History​

View transaction history:

# View all transactions
agentvault wallet history

# View wallet-specific
agentvault wallet history <wallet-id>

# Filter by type
agentvault wallet history --type send
agentvault wallet history --type receive

Export Wallet​

Export wallet keys for backup:

# Export to JSON
agentvault wallet export <wallet-id> --format json

# Export to mnemonic (use with caution)
agentvault wallet export <wallet-id> --format mnemonic --show

Cycles Management​

Top-up Cycles​

Add cycles to wallet:

# Top-up canister
agentvault wallet top-up <canister-id> --amount 1000000000000

# Options:
# --network icp - Target network
# --auto-refill - Enable auto-refill

Transfer Cycles​

Transfer cycles between wallets:

# Transfer cycles
agentvault wallet transfer --from <wallet-id> --to <wallet-id> --amount 1000000000000

Multi-send​

Send cycles to multiple recipients:

# Batch transfer
agentvault wallet multi-send --input transfers.json

# Input format:
# {
# "transfers": [
# { "to": "recipient-1", "amount": 1000000000000 },
# { "to": "recipient-2", "amount": 5000000000000 }
# ]
# }

Process Queue​

Process the transactions an agent's canister has queued:

# Prompts for the canister ID
agentvault wallet process-queue --agent-id <agent-id>

The command is meant to sign each pending transaction with the wallet's own key, record the signature on the canister and then send it. It refuses a transaction that asks for a signing threshold above 1, because threshold signing is not implemented. Today it calls the canister without a signing identity, and the canister refuses anonymous writes, so recording fails and nothing is sent.

Cross-Chain Operations​

Polkadot​

# Create Polkadot wallet
agentvault wallet create --chain polkadot

# Check balance
agentvault wallet balance <wallet-id> --chain polkadot

# Transfer tokens
agentvault wallet transfer --chain polkadot --to <address> --amount 1000

Solana​

# Create Solana wallet
agentvault wallet create --chain solana

# Check balance
agentvault wallet balance <wallet-id> --chain solana

# Transfer SOL
agentvault wallet transfer --chain solana --to <address> --amount 1.5

Security Best Practices​

Key Management​

  • Never share mnemonics - Store securely, never transmit
  • Use hardware wallets - For large holdings
  • Regular backups - Export wallet to secure location
  • Verify addresses - Double-check before sending
  • Use test transactions - Small amounts first

Transaction Safety​

  • Verify recipient address - Copy-paste carefully
  • Confirm amounts - Large transactions, double-check
  • Review transaction details - Before broadcasting
  • Monitor confirmations - Check on-chain status
  • Keep records - Save transaction IDs for reference

Recovery​

Lost mnemonic?

# Can only recover with mnemonic
agentvault wallet restore --mnemonic "word1 word2 word3 ..."

# No way to recover without mnemonic

Lost private key?

# Cannot recover
# Generate new wallet with remaining funds

Troubleshooting​

Wallet Not Found​

# List all wallets
agentvault wallet list

# Verify wallet ID
agentvault wallet info <wallet-id>

Insufficient Balance​

# Check balance
agentvault wallet balance

# Request from faucet (testnet only)
agentvault wallet faucet

# Purchase cycles
agentvault wallet purchase --amount 1000000000000

Transaction Failed​

# Check transaction queue
agentvault wallet queue

# Retry failed transaction
agentwallet wallet retry <tx-id>

# View error details
agentvault wallet history <tx-id> --details

Hardware Wallet Issues​

# Reconnect hardware wallet
agentvault wallet reconnect --hardware

# Check firmware
agentvault wallet check --hardware

# Reset connection
agentvault wallet disconnect --hardware

Advanced Features​

Multi-Signature Wallets​

Multi-signature wallets are not supported. For changes that need sign-off from several people, agentvault approve tracks approval requests and a signer quorum locally. It is not cryptographic multisig: signer names are not authenticated, and no transfer waits for an approval.

Derivation Paths​

Standard derivation paths for BIP-39/44:

# View derivation path
agentvault wallet info <wallet-id> --show-derivation

# Change derivation path
agentvault wallet set-derivation <wallet-id> --path "m/44'/223'/0'/0"

Custom Networks​

Add custom blockchain networks:

# Add network
agentvault network add --name custom --rpc https://custom-rpc.com

# Use network
agentvault deploy --network custom

Integration​

ICP Canister Funding​

# Top-up canister from wallet
agentvault wallet top-up <canister-id> --wallet <wallet-id>

# Auto-refill configuration
agentvault wallet configure <wallet-id> --auto-refill --threshold 100T

DApp Integration​

Connect wallet to Web3 DApps:

# Inject wallet into browser
agentvault wallet inject --browser chrome

# Use with DApp
agentvault wallet dapp-sign <url>

Next Steps​