📋 Prerequisites

Before installing SAM, ensure you have the following:

• Python 3.11+ installed on your system
• OpenAI API Key with sufficient credits for GPT usage
• Internet connection for blockchain operations
• Optional: Brave Search API key for web search functionality

🚀 Installation

Step 1: Clone the Repository

git clone https://github.com/prfagit/sam-framework
cd sam-framework

Step 2: Install Dependencies

# Using uv (recommended)
uv sync

# Or using pip
pip install -r requirements.txt

Step 3: Verify Installation

uv run sam --help

You should see the SAM CLI help output if installation was successful.

⚙️ Configuration

Required Setup

# Required
OPENAI_API_KEY=sk-your-openai-api-key-here
SAM_FERNET_KEY=your-generated-encryption-key

# Optional
BRAVE_API_KEY=your-brave-search-api-key
SAM_SOLANA_RPC_URL=https://api.mainnet-beta.solana.com

# Generate a new Fernet encryption key
uv run sam key generate

# Securely import your Solana private key
uv run sam key import

Configuration Validation

# Check your setup status
uv run sam setup

This command will verify:

• ✅ OpenAI API key configuration
• ✅ Encryption key presence
• ✅ Solana RPC connectivity
• ✅ Wallet configuration status

🎯 First Run

Start the Interactive Agent

# Start SAM in interactive mode
uv run sam

# Or specify a custom session
uv run sam --session trading_session

Initial Interaction

Once started, SAM will display a welcome message and you can begin interacting:

🤖 SAM • Solana Agent •
Type /help for commands. Ctrl+C to exit.

🤖 » check my balance

📖 Basic Usage Examples

Wallet Operations

# Check your complete wallet balance
"check my wallet balance"

# View SOL balance only
"show my SOL balance"

# Transfer SOL to another address
"send 0.1 SOL to [recipient_address]"

Trading Operations

# Buy on Pump.fun
"buy 0.01 SOL worth of BONK"

# Sell tokens
"sell 50% of my DOGE position"

# Get swap quotes
"get swap quote for 1 SOL to USDC on Jupiter"

Market Data

# View trending pairs
"show trending pairs on DexScreener"

# Search for specific tokens
"search for BONK trading pairs"

# Get detailed pair information
"get detailed info for pair [pair_address]"

Web Search

# Search for Solana news
"search for Solana ecosystem news"

# Find information about DEX launches
"find information about new DEX launches"

🔧 Advanced Configuration

Environment Variables Reference

| Variable | Description | Default | Required | |----------|-------------|---------|----------| | OPENAI_API_KEY | Your OpenAI API key | - | ✅ | | SAM_FERNET_KEY | Fernet encryption key | - | ✅ | | SAM_WALLET_PRIVATE_KEY | Solana private key | - | ❌ | | BRAVE_API_KEY | Brave Search API key | - | ❌ | | SAM_SOLANA_RPC_URL | Solana RPC endpoint | https://api.mainnet-beta.solana.com | ❌ | | SAM_DB_PATH | Database file path | .sam/sam_memory.db | ❌ | | RATE_LIMITING_ENABLED | Enable rate limiting | false | ❌ | | MAX_TRANSACTION_SOL | Max transaction size | 1000.0 | ❌ | | DEFAULT_SLIPPAGE | Default slippage % | 1 | ❌ | | LOG_LEVEL | Logging level | INFO | ❌ |

Security Configuration

# Enable production security settings
export RATE_LIMITING_ENABLED=true
export LOG_LEVEL=WARNING
export MAX_TRANSACTION_SOL=10.0

🧪 Testing Your Setup

Health Check

# Run comprehensive health diagnostics
uv run sam health

Test Commands

# Test wallet connection (no funds required)
"get wallet address"

# Test market data access
"show trending pairs"

# Test search functionality (if Brave API configured)
"search for Solana news"

🎉 Next Steps

Now that you have SAM configured and running, you can:

1. Explore the Tools: Use /tools command to see all available functions
2. Learn the CLI: Check /help for available commands
3. Configure Advanced Settings: Review the Configuration Guide
4. Understand Security: Read the Security Guide
5. View Architecture: Learn about SAM's Architecture

Getting Help

• Interactive Help: Type /help in SAM CLI
• Tool Documentation: Visit Available Tools
• Troubleshooting: Check Troubleshooting Guide