Agent Wallet

Multi-chain wallet skill for AI agents. one seed phrase, all chains.

intent

manage crypto wallets across solana, base, and ethereum without juggling separate seed phrases. use this skill when agents need to create wallets, check balances, send tokens (USDC or native), or bridge assets between chains. triggers: "create wallet", "check balance", "send USDC", "transfer", "my addresses", "wallet status".

inputs

environment variables (required for all operations except wallet creation)

• WALLET_SEED_PHRASE: 12 or 24-word BIP-39 seed phrase. must be set in .env. agents never input this via chat (security first).

environment variables (optional)

• NETWORK: testnet (default) or mainnet. controls which RPC endpoints and testnets are used.
• SOLANA_RPC: custom solana RPC URL. defaults to solana public RPC if not set.
• BASE_RPC: custom base RPC URL. defaults to base public RPC if not set.
• ETH_RPC: custom ethereum RPC URL. defaults to ethereum public RPC if not set.

external connections required

• solana blockchain: read/write to solana mainnet or testnet via RPC.
• ethereum blockchain: read/write to ethereum mainnet or testnet via RPC.
• base blockchain: read/write to base mainnet or testnet via RPC.
• circle CCTP V2: cross-chain token bridge for USDC transfers (read-only for contract state, write for bridge attestations).

runtime context

• wallet.js script available in scripts/ directory.
• node.js runtime with bip-39 and web3 libraries installed.

procedure

1. create new wallet (if user says "create wallet", "generate new wallet", etc.)

   • input: user command to create wallet.
   • run: node scripts/wallet.js create.
   • output: BIP-39 seed phrase (12 words), derived addresses for solana, base, and ethereum, instruction to save seed to .env.
   • seed phrase shown exactly once. never logged or re-displayed after creation.

2. import existing wallet (if user says "import wallet", "import my seed", etc.)

   • input: user request to import.
   • run: no script execution. instead, respond with instruction: "add your seed phrase to .env as WALLET_SEED_PHRASE (12 or 24 words), then say 'show my addresses' to verify."
   • output: user instruction text. no seed phrases accepted in chat.

3. show addresses (if user says "show my addresses", "what's my wallet", "my wallet addresses", etc.)

   • input: user command. requires WALLET_SEED_PHRASE set in .env.
   • run: node scripts/wallet.js addresses.
   • output: list of derived addresses (solana, base, ethereum). does not expose seed phrase.

4. check balance (if user says "check balance", "how much USDC", "balance on base", etc.)

   • input: optional chain name (solana, base, ethereum, or all). requires WALLET_SEED_PHRASE set in .env.
   • run: node scripts/wallet.js balance [chain] where chain is optional.
   • run variations:
     • node scripts/wallet.js balance for all chains.
     • node scripts/wallet.js balance solana for solana only.
     • node scripts/wallet.js balance base for base only.
   • output: native token balance (SOL, ETH) and USDC balance for each chain queried. includes chain name and timestamp.

5. transfer tokens (if user says "send 10 USDC to...", "transfer 5 SOL to...", etc.)

   • input: chain name, token symbol (SOL, ETH, USDC), amount (numeric), recipient address.
   • run: node scripts/wallet.js transfer <chain> <token> <amount> <recipient>.
   • validate inputs: recipient address format matches chain (solana base58 or EVM 0x hex). amount is positive number.
   • output: transaction hash, confirmation count, final status (success or failure with reason).

6. bridge USDC cross-chain (if user says "bridge 10 USDC from base to solana", "bridge USDC", etc.)

   • input: source chain, destination chain, amount (USDC).
   • run: node scripts/wallet.js bridge <from-chain> <to-chain> <amount>.
   • supported routes: base <-> solana, ethereum <-> base, solana <-> ethereum.
   • output: burn transaction hash on source chain, attestation request ID, mint transaction hash on destination chain. includes note: "bridging takes 1-5 minutes (burn > attestation > mint)."

7. show chain info (if user says "what chains supported", "chain info", etc.)

   • input: user command.
   • run: node scripts/wallet.js chains.
   • output: list of supported chains (solana, base, ethereum), network (testnet/mainnet), RPC endpoints in use, USDC contract addresses per chain.

decision points

if WALLET_SEED_PHRASE is not set in .env

• for "create wallet" command: proceed with creation (no seed needed yet). user will be instructed to save the generated seed to .env.
• for "import wallet" command: respond with instruction to add seed to .env file. do not accept seed phrase via chat input.
• for "show addresses", "check balance", "transfer", or "bridge" commands: return error "WALLET_SEED_PHRASE not set in .env. create a new wallet or import an existing one first."

if seed phrase format is invalid (not 12 or 24 words, or invalid BIP-39 checksum)

• return error "invalid seed phrase. must be 12 or 24 words. verify format and try again."

if user requests transfer or bridge but balance is insufficient

• check balance first via step 4.
• if native token balance (for gas) is below minimum required: return error "insufficient balance for gas on . required: 0.XXX . current: 0.YYY. top up wallet first."
• if USDC/token balance is below transfer amount: return error "insufficient balance. required: . current: ."

if recipient address is invalid or malformed

• solana addresses: must be valid base58, 43-44 characters.
• EVM addresses: must start with 0x, be 42 characters, and be valid hex.
• if invalid: return error "invalid address format. verify recipient address and try again."

if bridge route is not supported

• only supported routes: base <-> solana, ethereum <-> base, solana <-> ethereum.
• if user requests bridge between other chains: return error "bridge from to not supported. use one of these routes: base <-> solana, ethereum <-> base, solana <-> ethereum."

if RPC endpoint is unreachable or rate-limited

• retry up to 3 times with exponential backoff (1s, 2s, 4s).
• if still failing after retries: return error "RPC endpoint unreachable. check network connection or use a custom RPC via _RPC env var."

if bridge attestation times out (no attestation received after 10 minutes)

• return error "bridge attestation timeout. transaction may still complete. check destination chain in 5 minutes or contact support with burn tx hash: ."

output contract

create wallet

format: plaintext box with dividers. includes seed phrase in bordered box, derived addresses (solana as base58, base and ethereum as 0x hex), .env instruction, network label (testnet/mainnet).

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔐 NEW WALLET GENERATED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

⚠️  CRITICAL: Save this seed phrase securely!
    It will NOT be shown again.
    Anyone with this phrase can access your funds.

Seed Phrase:
┌────────────────────────────────────────────┐
│ word1 word2 word3 word4 word5 word6        │
│ word7 word8 word9 word10 word11 word12     │
└────────────────────────────────────────────┘

Your Addresses:
├─ Solana:   7xK9...mP4q
├─ Base:     0x7a3B...4f2E
└─ Ethereum: 0x7a3B...4f2E (same as Base)

Add to .env:
WALLET_SEED_PHRASE="word1 word2 word3 ..."

Network: TESTNET
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

show addresses

format: plaintext list of addresses per chain with abbreviations (first 8 chars, last 4 chars). include full addresses in clickable format if platform supports it.

Solana:   7xK9fR2m...mP4q
Base:     0x7a3B9fF2...4f2E
Ethereum: 0x7a3B9fF2...4f2E

check balance

format: plaintext table per chain. columns: chain, native token (symbol, balance), USDC (balance). include timestamp and network (testnet/mainnet).

Chain    Native Balance  USDC Balance
────────────────────────────────────
Solana   2