Solana Wallet Setup

Set up and manage Solana wallets for autonomous agent payments via the Machine Payments Protocol.

Overview

Agents need Solana wallets to:

• Hold USDC for MPP payments

• Sign payment transactions

• Receive refunds and credits

• Track payment history on-chain

This guide covers wallet creation, funding, security, and operational best practices.

Creating a Wallet

Using solana-keygen

The Solana CLI provides wallet generation tools.

Install Solana CLI:

sh -c "$(curl -sSfL https://release.solana.com/stable/install)"

Generate new wallet:

solana-keygen new --outfile ~/.config/solana/agent-wallet.json

This creates a new keypair and saves it to the specified file.

Important: Save the seed phrase displayed during generation. This is the only way to recover the wallet if the key file is lost.

Programmatic generation

Generate wallets programmatically for agent fleets:

import { Keypair } from '@solana/web3.js'
import fs from 'fs'

// Generate new keypair
const wallet = Keypair.generate()

// Save to file
const secretKey = Array.from(wallet.secretKey)
fs.writeFileSync(
  '~/.config/solana/agent-wallet.json',
  JSON.stringify(secretKey)
)

console.log(`Public key: ${wallet.publicKey.toBase58()}`)
console.log('Secret key saved to file')

HD Wallet derivation

For managing multiple agents from a single seed:

import { Keypair } from '@solana/web3.js'
import { derivePath } from 'ed25519-hd-key'
import * as bip39 from 'bip39'

// Generate or load mnemonic
const mnemonic = bip39.generateMnemonic()
console.log('Mnemonic:', mnemonic)

// Derive keypairs for multiple agents
function deriveAgent(mnemonic: string, index: number): Keypair {
  const seed = bip39.mnemonicToSeedSync(mnemonic)
  const path = `m/44'/501'/${index}'/0'`
  const derived = derivePath(path, seed.toString('hex')).key
  return Keypair.fromSeed(derived)
}

// Create 10 agent wallets
for (let i = 0; i < 10; i++) {
  const agent = deriveAgent(mnemonic, i)
  console.log(`Agent ${i}: ${agent.publicKey.toBase58()}`)
}

Funding Your Wallet

Agents need SOL for transaction fees and USDC for payments.

SOL for transaction fees

Devnet (for testing):

solana airdrop 2 <wallet-address> --url devnet

Mainnet-beta (production):

Transfer SOL from an exchange or existing wallet:

solana transfer <agent-wallet-address> 0.1 \
  --from ~/.config/solana/funding-wallet.json \
  --url mainnet-beta

Recommended balance: 0.1 SOL per agent (supports ~100,000 transactions)

USDC for payments

Devnet USDC:

Use the SPL Token Faucet:

• Visit spl-token-faucet.com

• Enter your wallet address

• Request devnet USDC

Mainnet-beta USDC:

Transfer USDC from exchange or existing wallet:

spl-token transfer \
  EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  100 \
  <agent-wallet-address> \
  --from ~/.config/solana/funding-wallet.json \
  --url mainnet-beta

USDC Mint Address (mainnet-beta):

EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

Check balances

# Check SOL balance
solana balance <wallet-address> --url mainnet-beta

# Check USDC balance
spl-token balance \
  EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --owner <wallet-address> \
  --url mainnet-beta

Wallet Security

Encrypted storage

Never store unencrypted private keys in production.

Encrypt with passphrase:

solana-keygen new \
  --outfile ~/.config/solana/agent-wallet.json \
  --no-bip39-passphrase

Enter strong passphrase when prompted.

Load encrypted wallet:

import { Keypair } from '@solana/web3.js'
import fs from 'fs'
import * as crypto from 'crypto'

async function loadEncryptedWallet(
  path: string,
  passphrase: string
): Promise<Keypair> {
  const encrypted = fs.readFileSync(path)

  // Decrypt (implementation depends on encryption method)
  const decrypted = decrypt(encrypted, passphrase)

  return Keypair.fromSecretKey(new Uint8Array(decrypted))
}

Environment variables

Load wallet from environment for containerized deployments:

import { Keypair } from '@solana/web3.js'

const secretKey = JSON.parse(process.env.SOLANA_PRIVATE_KEY!)
const wallet = Keypair.fromSecretKey(new Uint8Array(secretKey))

Kubernetes secret:

apiVersion: v1
kind: Secret
metadata:
  name: agent-wallet
type: Opaque
stringData:
  private-key: '[1,2,3,...]'  # Secret key array

Hardware wallet integration

For maximum security, use hardware wallets:

import { Transaction } from '@solana/web3.js'
import TransportNodeHid from '@ledgerhq/hw-transport-node-hid'
import Solana from '@ledgerhq/hw-app-solana'

async function signWithLedger(tx: Transaction): Promise<Transaction> {
  const transport = await TransportNodeHid.create()
  const solana = new Solana(transport)

  const path = "44'/501'/0'/0'"  // Derivation path
  const signature = await solana.signTransaction(path, tx.serializeMessage())

  tx.addSignature(signature.publicKey, signature.signature)

  return tx
}

Multi-Wallet Strategies

Hot wallet + Cold storage

Keep most funds in cold storage, refill hot wallet as needed:

class WalletManager {
  private hotWallet: Keypair
  private coldWalletAddress: string
  private refillThreshold: number

  constructor(
    hotWallet: Keypair,
    coldWalletAddress: string,
    refillThreshold: number = 10_000_000  // 10 USDC
  ) {
    this.hotWallet = hotWallet
    this.coldWalletAddress = coldWalletAddress
    this.refillThreshold = refillThreshold
  }

  async checkAndRefill(connection: Connection) {
    const balance = await this.getUSDCBalance(connection)

    if (balance < this.refillThreshold) {
      console.log('Hot wallet low, requesting refill from cold storage')
      await this.notifyRefillNeeded()
    }
  }

  private async getUSDCBalance(connection: Connection): Promise<number> {
    const tokenAccount = await connection.getTokenAccountBalance(
      this.hotWallet.publicKey
    )
    return tokenAccount.value.uiAmount || 0
  }

  private async notifyRefillNeeded() {
    // Send notification to ops team
    // Manual transfer from cold wallet required
  }
}

Agent fleet management

Manage wallets for multiple agents:

interface AgentWallet {
  id: string
  keypair: Keypair
  purpose: string
  dailyLimit: number
  spentToday: number
}

class FleetManager {
  private wallets: Map<string, AgentWallet>

  constructor() {
    this.wallets = new Map()
  }

  registerAgent(
    id: string,
    keypair: Keypair,
    purpose: string,
    dailyLimit: number
  ) {
    this.wallets.set(id, {
      id,
      keypair,
      purpose,
      dailyLimit,
      spentToday: 0
    })
  }

  getWallet(agentId: string): Keypair {
    const wallet = this.wallets.get(agentId)
    if (!wallet) throw new Error(`Agent ${agentId} not found`)
    return wallet.keypair
  }

  recordSpending(agentId: string, amountUSDC: number) {
    const wallet = this.wallets.get(agentId)
    if (!wallet) throw new Error(`Agent ${agentId} not found`)

    wallet.spentToday += amountUSDC

    if (wallet.spentToday > wallet.dailyLimit) {
      throw new Error(`Agent ${agentId} exceeded daily limit`)
    }
  }

  async resetDailyLimits() {
    for (const wallet of this.wallets.values()) {
      wallet.spentToday = 0
    }
  }

  async auditFleet(connection: Connection) {
    const report = []

    for (const [id, wallet] of this.wallets.entries()) {
      const balance = await this.getBalance(connection, wallet.keypair)

      report.push({
        id,
        purpose: wallet.purpose,
        balanceSOL: balance.sol,
        balanceUSDC: balance.usdc,
        spentToday: wallet.spentToday,
        remainingLimit: wallet.dailyLimit - wallet.spentToday
      })
    }

    return report
  }

  private async getBalance(
    connection: Connection,
    keypair: Keypair
  ): Promise<{ sol: number; usdc: number }> {
    const sol = await connection.getBalance(keypair.publicKey)

    // Get USDC balance (simplified)
    const usdc = 0  // Implement token account lookup

    return {
      sol: sol / 1e9,  // Convert lamports to SOL
      usdc
    }
  }
}

Key Rotation

Rotate agent wallet keys periodically for security.

Rotation process

async function rotateAgentWallet(
  oldWallet: Keypair,
  connection: Connection
): Promise<Keypair> {
  // 1. Generate new wallet
  const newWallet = Keypair.generate()

  console.log('New wallet:', newWallet.publicKey.toBase58())

  // 2. Transfer all SOL
  const solBalance = await connection.getBalance(oldWallet.publicKey)

  const transferSOL = new Transaction().add(
    SystemProgram.transfer({
      fromPubkey: oldWallet.publicKey,
      toPubkey: newWallet.publicKey,
      lamports: solBalance - 5000  // Leave small amount for USDC transfer fee
    })
  )

  await connection.sendTransaction(transferSOL, [oldWallet])

  // 3. Transfer all USDC
  // (Implementation depends on token account structure)

  // 4. Update configuration to use new wallet
  console.log('Rotation complete. Update agent configuration.')

  return newWallet
}

Automated rotation schedule

class WalletRotationManager {
  private rotationInterval: number = 90 * 24 * 60 * 60 * 1000  // 90 days

  async scheduleRotation(
    wallet: Keypair,
    connection: Connection,
    onRotate: (newWallet: Keypair) => void
  ) {
    setInterval(async () => {
      console.log('Starting scheduled wallet rotation...')

      const newWallet = await rotateAgentWallet(wallet, connection)

      // Notify application of new wallet
      onRotate(newWallet)

      // Update reference
      wallet = newWallet

    }, this.rotationInterval)
  }
}

Devnet vs Mainnet-beta

Devnet configuration

For testing and development:

const mpp = new MoltMPPClient({
  solanaRpc: 'https://api.devnet.solana.com',
  wallet: devnetWallet,
  network: 'devnet'
})

Advantages:

• Free SOL via airdrop

• Free USDC via faucet

• Safe for testing without financial risk

• Faster iteration

Limitations:

• Not all services support devnet

• Different USDC mint address

• Network may be unstable

Mainnet-beta configuration

For production deployments:

const mpp = new MoltMPPClient({
  solanaRpc: 'https://api.mainnet-beta.solana.com',
  wallet: mainnetWallet,
  network: 'mainnet-beta'
})

Advantages:

• Real services and APIs

• Production-grade reliability

• Actual value exchange

Considerations:

• Requires real SOL and USDC

• Transaction fees accumulate

• Irreversible mistakes

Monitoring and Alerts

Track wallet health and set up alerts.

Balance monitoring

async function monitorWalletBalance(
  connection: Connection,
  wallet: Keypair,
  thresholds: {
    minSOL: number
    minUSDC: number
  }
) {
  setInterval(async () => {
    const sol = await connection.getBalance(wallet.publicKey)
    const solAmount = sol / 1e9

    if (solAmount < thresholds.minSOL) {
      console.warn(`⚠️  Low SOL balance: ${solAmount} SOL`)
      // Send alert
    }

    // Check USDC balance
    // ...

  }, 60000)  // Check every minute
}

Transaction monitoring

async function monitorTransactions(
  connection: Connection,
  wallet: Keypair
) {
  const signatures = await connection.getSignaturesForAddress(
    wallet.publicKey,
    { limit: 10 }
  )

  for (const sig of signatures) {
    const tx = await connection.getTransaction(sig.signature)

    console.log(`Transaction: ${sig.signature}`)
    console.log(`  Status: ${sig.confirmationStatus}`)
    console.log(`  Slot: ${sig.slot}`)
  }
}

Production Checklist

Before deploying agent wallets to production:

• Wallet keys encrypted at rest

• Keys stored in secrets manager (Vault, AWS Secrets Manager)

• Environment variables configured correctly

• SOL balance sufficient for 1000+ transactions

• USDC balance aligned with daily spending limits

• Balance monitoring and alerts configured

• Key rotation schedule established

• Backup of seed phrase in secure offline storage

• Multi-sig or hardware wallet for high-value operations

• Audit logging enabled for all wallet operations

Next Steps

• OpenClaw Integration: Use wallets with agents

• Approval Policies: Configure spending limits

• Security: Advanced security practices

Resources

• Solana Cookbook: solanacookbook.com/references/keypairs-and-wallets

• SPL Token Docs: spl.solana.com/token

• Discord: discord.gg/moltmpp - #wallet-help