SAM Framework uses environment variables for configuration with sensible defaults. Configuration is loaded automatically on startup and can be validated using the CLI.
Environment-Based
Configuration via environment variables with .env file support
Secure by Default
Encrypted key storage and secure credential management
Runtime Validation
Configuration validation with helpful error messages
SAM supports multiple configuration methods with automatic loading priority:
sam.toml or $XDG_CONFIG_HOME/sam/sam.toml).env File (auto-loaded)# sam.toml [llm] provider = "anthropic" model = "claude-3-5-sonnet-latest" [safety] max_transaction_sol = 5.0 default_slippage = 2.0 [tools] enable_solana_tools = true enable_pump_fun_tools = true enable_jupiter_tools = true enable_dexscreener_tools = true enable_search_tools = false
# .env LLM_PROVIDER=anthropic ANTHROPIC_API_KEY=sk-ant-your-key-here SAM_FERNET_KEY=your-generated-key SAM_SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| LLM_PROVIDER | Set to openai | - | Yes |
| OPENAI_API_KEY | Your OpenAI API key | - | Yes |
| OPENAI_MODEL | Model name | gpt-4o-mini | No |
| OPENAI_BASE_URL | Custom endpoint | OpenAI default | No |
LLM_PROVIDER=openai OPENAI_API_KEY=sk-your-openai-api-key-here OPENAI_MODEL=gpt-4o-mini
| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| SAM_FERNET_KEY | Fernet encryption key | auto-generated | Yes |
| SAM_WALLET_PRIVATE_KEY | Solana private key | - | No* |
# Generate encryption key sam key generate # Import private key securely (recommended) sam key import
*Private key can be imported via sam key import for better security
SAM uses a configurable middleware pipeline for tool execution, logging, rate limiting, and error handling.
# Set middleware configuration export SAM_MIDDLEWARE_JSON='{ "logging": { "include_args": false, "include_result": false, "only": [], "exclude": [] }, "rate_limit": { "enabled": true, "map": { "search_web": {"type": "search", "identifier_field": "query"}, "search_news": {"type": "search", "identifier_field": "query"}, "get_swap_quote": {"type": "jupiter"}, "jupiter_swap": {"type": "jupiter"}, "pump_fun_buy": {"type": "pump_fun_buy", "identifier_field": "mint"}, "pump_fun_sell": {"type": "pump_fun_sell", "identifier_field": "mint"} } }, "retry": [ {"only": ["search_web", "search_news"], "max_retries": 2, "base_delay": 0.25}, {"only": ["get_swap_quote", "jupiter_swap"], "max_retries": 3, "base_delay": 0.25}, {"only": ["pump_fun_buy", "pump_fun_sell"], "max_retries": 2, "base_delay": 0.25} ] }'
{ "logging": { "include_args": true, "include_result": true, "only": ["get_balance", "transfer_sol"], "exclude": ["search_web"] } }
{ "rate_limit": { "enabled": true, "map": { "tool_name": { "type": "category_name", "identifier_field": "field_name" } } } }
{ "retry": [ { "only": ["tool_name"], "max_retries": 3, "base_delay": 0.25 } ] }
# sam.toml [middleware.logging] include_args = false include_result = false [middleware.rate_limit] enabled = true [middleware.rate_limit.map.search_web] type = "search" identifier_field = "query" [[middleware.retry]] only = ["search_web", "search_news"] max_retries = 2 base_delay = 0.25
SAM provides multiple ways to manage your Solana private key securely:
# Use the secure import command uv run sam key import # Follow the interactive prompts to import your key # The key will be encrypted and stored in your OS keyring
Benefits:
# Check your configuration status uv run sam setup
This command validates:
# Run comprehensive health check uv run sam health
Health Check Components:
For production deployments, consider using dedicated RPC endpoints:
# High-performance RPC endpoints SAM_SOLANA_RPC_URL=https://your-fast-rpc.com # Alternative options: # https://api.mainnet-beta.solana.com (default) # https://solana-mainnet.g.alchemy.com/v2/YOUR_API_KEY # https://rpc.ankr.com/solana
# Custom database location SAM_DB_PATH=/path/to/sam_database.db # Use in-memory database (not recommended for production) SAM_DB_PATH=:memory:
# Log levels: DEBUG, INFO, WARNING, ERROR, CRITICAL LOG_LEVEL=DEBUG # Verbose logging for development LOG_LEVEL=WARNING # Minimal logging for production # Disable all logging (not recommended) LOG_LEVEL=NO
For web search functionality:
# Get API key from https://brave.com/search/api/ BRAVE_API_KEY=your_brave_api_key_here
Features enabled:
# .env.production OPENAI_API_KEY=sk-production-key SAM_FERNET_KEY=production-encryption-key SAM_SOLANA_RPC_URL=https://production-rpc-endpoint.com RATE_LIMITING_ENABLED=true MAX_TRANSACTION_SOL=10.0 DEFAULT_SLIPPAGE=5 LOG_LEVEL=WARNING SAM_DB_PATH=/data/sam/production.db
# Development cp .env.example .env.dev export $(cat .env.dev | xargs) # Production cp .env.example .env.prod export $(cat .env.prod | xargs)
Configuration Error: If you see "SAM_FERNET_KEY is required", run sam key generate and add the key to your .env file.
API Key Error: Ensure your OpenAI API key is valid and has sufficient credits. Check https://platform.openai.com/api-keys
# Test OpenAI API connectivity uv run sam setup # Test Solana RPC connection uv run sam health # View current configuration uv run sam config # (if implemented)
OPENAI_API_KEY=sk-your-key SAM_FERNET_KEY=your-generated-key
OPENAI_API_KEY=sk-dev-key SAM_FERNET_KEY=dev-encryption-key LOG_LEVEL=DEBUG RATE_LIMITING_ENABLED=false
OPENAI_API_KEY=sk-prod-key SAM_FERNET_KEY=prod-encryption-key SAM_SOLANA_RPC_URL=https://production-rpc.com RATE_LIMITING_ENABLED=true MAX_TRANSACTION_SOL=5.0 LOG_LEVEL=WARNING
OPENAI_API_KEY - Valid OpenAI API key configuredSAM_FERNET_KEY - Fernet encryption key generatedsam key importsam setup passes all validation checkssam health shows green statusRemember: Never commit your .env file or share your private keys. Use the secure key import feature for maximum security.