Solana AI Terminal

# Solana Wallet Setup Guide This guide explains how to create and configure a Solana wallet for use with the MCP server. ## Quick Start ### Option 1: Generate a New Wallet (Recommended) Create a brand new Solana wallet with a single command: ```bash pnpm derive-key ``` This will output: - 📝 **12-word mnemonic phrase** - Save this securely! It's your wallet backup - 🔐 **Public Key (Address)** - Your wallet's public address - 🔒 **Private Key (Base58)** - For the `AGENT_SECRET_KEY` environment variable **Example output:** ``` ============================================================ CREATING NEW SOLANA WALLET ============================================================ 🔑 NEW WALLET CREATED ------------------------------------------------------------ 📝 MNEMONIC (12 words): shoe aim describe refuse digital way purity great candy thank spike among ⚠️ SAVE THIS MNEMONIC - IT'S YOUR WALLET BACKUP! ------------------------------------------------------------ 🔐 Public Key (Address): B9x6yerkSVxxjUpeh3UytCs5WFrnZWEGckH7Z6z1kKcv 🔒 Private Key (Base58 - for AGENT_SECRET_KEY): xQJs99aR2PBpEHkvNZ8WNrSgsBGzibYaz4sdro7DSQtviETUEZDrvpj4gYff7Qc5VXX7RYPzgsEFgLYWvd7mcpr ============================================================ 💾 Add this to your .env file: ============================================================ AGENT_SECRET_KEY=xQJs99aR2PBpEHkvNZ8WNrSgsBGzibYaz4sdro7DSQtviETUEZDrvpj4gYff7Qc5VXX7RYPzgsEFgLYWvd7mcpr ENVIRONMENT=DEVNET ============================================================ ``` ### Option 2: Use Existing Mnemonic If you already have a Solana wallet mnemonic (e.g., from Phantom, Solflare), derive your keys: ```bash pnpm derive-key --mnemonic "your twelve word mnemonic phrase here" ``` --- ## Configuration ### Step 1: Update `.env` File Copy the output from the wallet generation and add it to your `.env` file: ```bash # Network Configuration ENVIRONMENT=DEVNET # DEVNET or TESTNET # Wallet Configuration AGENT_SECRET_KEY=your_base58_private_key_here # Server Configuration USE_STREAMABLE_HTTP=false PORT=3000 HOST=127.0.0.1 ``` ### Step 2: Get Devnet SOL You need SOL tokens to interact with the Solana blockchain. For testing on Devnet: **Option A: Web Faucet** 1. Visit https://faucet.solana.com/ 2. Paste your public key (address) 3. Select "Devnet" 4. Request airdrop (up to 5 SOL) **Option B: CLI (if you have Solana CLI installed)** ```bash solana airdrop 2 YOUR_PUBLIC_KEY --url devnet ``` **Option C: Use MCP Tool** Once your server is running, you can use the `request_airdrop` tool to get Devnet SOL programmatically. --- ## Key Formats Solana uses different key formats for different purposes: ### Mnemonic (Seed Phrase) - **Format**: 12 or 24 words - **Example**: `shoe aim describe refuse digital way purity great candy thank spike among` - **Purpose**: Human-readable backup that can restore your entire wallet - **⚠️ SECURITY**: Never share this! Anyone with your mnemonic can access your wallet ### Public Key (Address) - **Format**: Base58-encoded string (32-44 characters) - **Example**: `B9x6yerkSVxxjUpeh3UytCs5WFrnZWEGckH7Z6z1kKcv` - **Purpose**: Your wallet's address - share this to receive SOL/tokens - **✅ SAFE**: This can be shared publicly ### Private Key (Secret Key) - **Format**: Base58-encoded string (87-88 characters) - **Example**: `xQJs99aR2PBpEHkvNZ8WNrSgsBGzibYaz4sdro7DSQtviETUEZDrvpj4gYff7Qc5VXX7RYPzgsEFgLYWvd7mcpr` - **Purpose**: Used by the MCP server to sign transactions - **⚠️ SECURITY**: Never share this! Anyone with your private key can control your wallet --- ## Derivation Path The wallet generation uses the standard Solana derivation path: ``` m/44'/501'/0'/0' ``` This is the same path used by popular wallets like: - Phantom - Solflare - Sollet If you need to derive multiple accounts from the same mnemonic: - Account 0: `m/44'/501'/0'/0'` - Account 1: `m/44'/501'/1'/0'` - Account 2: `m/44'/501'/2'/0'` --- ## Security Best Practices ### ✅ DO: - Save your mnemonic in a secure location (password manager, encrypted file) - Use a dedicated test wallet for Devnet/Testnet - Keep separate wallets for development and production - Set appropriate file permissions on `.env` (already gitignored) - Use environment variables for private keys (never hardcode) ### ❌ DON'T: - Commit `.env` or private keys to version control - Share your mnemonic or private key with anyone - Use your main wallet for testing - Store keys in plain text on cloud services - Screenshot or email your private keys --- ## Networks ### Devnet (Development) - **RPC URL**: `https://api.devnet.solana.com` - **Purpose**: Testing and development - **Explorer**: https://explorer.solana.com/?cluster=devnet - **Faucet**: https://faucet.solana.com/ - **Token Value**: No real value - free test SOL ### Testnet (Testing) - **RPC URL**: `https://api.testnet.solana.com` - **Purpose**: Pre-production testing - **Explorer**: https://explorer.solana.com/?cluster=testnet - **Faucet**: https://faucet.solana.com/ - **Token Value**: No real value - free test SOL ### Mainnet (Production) - **RPC URL**: `https://api.mainnet-beta.solana.com` - **Purpose**: Production use with real value - **⚠️ WARNING**: Real money - use with caution! - **Token Value**: Real SOL with monetary value --- ## Troubleshooting ### Invalid Private Key Format **Error**: `Invalid AGENT_SECRET_KEY format. Expected base58-encoded Solana private key` **Solution**: Make sure you're using the base58-encoded private key (87-88 characters), not the hex format or mnemonic. ### Insufficient Balance **Error**: Transaction fails due to insufficient balance **Solution**: 1. Check your balance with `get_balance` tool 2. Request airdrop: `request_airdrop` tool or faucet 3. Wait a few seconds and retry ### Wrong Network **Error**: Account not found or unexpected behavior **Solution**: 1. Check `ENVIRONMENT` in `.env` (DEVNET vs TESTNET) 2. Make sure your wallet has SOL on the correct network 3. Restart the server after changing `.env` --- ## Wallet Recovery If you have your mnemonic, you can always recover your wallet: ```bash pnpm derive-key --mnemonic "your saved twelve word phrase" ``` This will output your public key and private key, allowing you to update your `.env` file. --- ## Advanced: Multiple Accounts To derive additional accounts from the same mnemonic, you'll need to modify the derivation path in `derive-solana-key.cjs`: ```javascript // Account 0 (default) const path = "m/44'/501'/0'/0'"; // Account 1 const path = "m/44'/501'/1'/0'"; // Account 2 const path = "m/44'/501'/2'/0'"; ``` --- ## Need Help? - **Solana Documentation**: https://docs.solana.com/ - **Solana Discord**: https://discord.gg/solana - **Devnet Faucet**: https://faucet.solana.com/ - **Explorer**: https://explorer.solana.com/ --- ## Quick Reference | Command | Description | |---------|-------------| | `pnpm derive-key` | Create new wallet | | `pnpm derive-key --mnemonic "..."` | Derive from existing mnemonic | | `pnpm build` | Build the MCP server | | `pnpm start` | Start the MCP server | | `pnpm dev` | Start in development mode | --- **Remember**: Always use test networks (Devnet/Testnet) for development and never commit private keys to version control! 🔒