solana-trader

What this skill does

# Solana Trader 🚀

A comprehensive Solana wallet management and trading skill for Clawdbot. Manage your Solana portfolio, check balances, view transaction history, and swap tokens using Jupiter DEX aggregator.

## Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `SOLANA_KEYPAIR_PATH` | Path to wallet keypair JSON file | Yes |
| `SOLANA_RPC_URL` | Custom RPC endpoint (default: mainnet-beta) | No |
| `JUPITER_API_KEY` | Jupiter API key for authenticated requests | No |
| `HELIUS_API_KEY` | Helius API key for enhanced transaction data | No |
| `SHYFT_API_KEY` | Shyft API key for transaction history | No |
| `QUICKNODE_RPC_URL` | QuickNode RPC endpoint | No |
| `ALCHEMY_RPC_URL` | Alchemy Solana RPC endpoint | No |

## 🌐 Free Public RPC Endpoints (No API Key Required)

| Provider | Endpoint | Notes |
|----------|----------|-------|
| Solana Foundation | `https://api.mainnet-beta.solana.com` | Official, rate limited |
| PublicNode | `https://solana-rpc.publicnode.com` | Privacy-first, fast |
| Ankr | `https://rpc.ankr.com/solana` | Free public endpoint |
| Project Serum | `https://solana-api.projectserum.com` | Community maintained |

> ⚠️ **Rate Limits**: Public endpoints typically limit to ~100 requests/10 seconds. For production or high-frequency trading, use a paid RPC provider.

### RPC Selection Strategy

**Default behavior (no API keys configured):**
1. Try `SOLANA_RPC_URL` if set
2. Fall back to free public endpoints in order:
   - `https://api.mainnet-beta.solana.com`
   - `https://solana-rpc.publicnode.com`
   - `https://rpc.ankr.com/solana`

**When to upgrade to paid RPC:**
- Rate limit errors (429 Too Many Requests)
- High-frequency trading or MEV
- Need for enhanced transaction data (Helius)
- Production applications requiring 99.9% uptime
- WebSocket subscriptions for real-time updates

**If rate limited**, ask user: "Would you like to configure a paid RPC provider? Options: Helius, QuickNode, Alchemy, Shyft"

## 💎 Referral Fee Configuration

This skill includes a small platform fee (0.2%) on swaps to support development. The fee is transparently disclosed to users before each swap.

| Variable | Value | Description |
|----------|-------|-------------|
| `PLATFORM_FEE_BPS` | 20 | 0.2% platform fee (20 basis points) |
| `FEE_ACCOUNT` | `8KDDpruBwpTzJLKEcfv8JefKSVYWYE53FV3B2iLD6bNN` | Solana wallet to receive fees |

**Fee Breakdown:**
- User pays: 0.2% of swap output
- Developer receives: 97.5% of fee (0.195%)
- Jupiter receives: 2.5% of fee (0.005%)

**Example**: On a 100 USDC swap output:
- Total fee: 0.20 USDC
- You receive: ~0.195 USDC
- Jupiter receives: ~0.005 USDC

## Setup Verification

```bash
# Check wallet address
solana address --keypair "$SOLANA_KEYPAIR_PATH"

# Check Solana CLI config
solana config get

# Test RPC connection
solana cluster-version
```

### Import Private Key

If you only have a private key (base58 string or byte array), convert it to keypair JSON:

**From Base58 private key:**
```bash
# Install solana-keygen if needed
# Your private key looks like: 5K1gR...xyz (base58 string)

echo "Enter your base58 private key:"
read -s PRIVATE_KEY

# Convert to keypair JSON (requires Node.js)
node -e "
const bs58 = require('bs58');
const key = bs58.decode('$PRIVATE_KEY');
console.log(JSON.stringify(Array.from(key)));
" > ~/.config/solana/imported-wallet.json

export SOLANA_KEYPAIR_PATH=~/.config/solana/imported-wallet.json
```

**From byte array (e.g., Phantom export):**
```bash
# If you have a byte array like [12,34,56,...]
echo '[12,34,56,78,...]' > ~/.config/solana/imported-wallet.json
export SOLANA_KEYPAIR_PATH=~/.config/solana/imported-wallet.json
```

**From seed phrase (mnemonic):**
```bash
# Use solana-keygen to recover
solana-keygen recover -o ~/.config/solana/recovered-wallet.json
# Enter your 12/24 word seed phrase when prompted

export SOLANA_KEYPAIR_PATH=~/.config/solana/recovered-wallet.json
```

> ⚠️ **Security**: Never share your private key or seed phrase. Store keypair files with restricted permissions: `chmod 600 ~/.config/solana/*.json`

---

## 💰 Balance Commands

### Check SOL Balance

```bash
solana balance --keypair "$SOLANA_KEYPAIR_PATH"
```

### List All Token Accounts

```bash
spl-token accounts --owner $(solana address --keypair "$SOLANA_KEYPAIR_PATH")
```

### Check Specific Token Balance

```bash
# Replace <MINT_ADDRESS> with token mint
spl-token balance <MINT_ADDRESS> --owner $(solana address --keypair "$SOLANA_KEYPAIR_PATH")
```

### Get Portfolio Summary

```bash
# Get wallet address
WALLET=$(solana address --keypair "$SOLANA_KEYPAIR_PATH")

# Get SOL balance
SOL_BALANCE=$(solana balance --keypair "$SOLANA_KEYPAIR_PATH" | awk '{print $1}')

# Get all token accounts
spl-token accounts --owner $WALLET
```

---

## 📜 Transaction History

### View Recent Transactions

Multiple RPC providers supported. Default uses native Solana RPC (no API key required).

**Option 1: Solana RPC (default, no API key)**
```bash
WALLET=$(solana address --keypair "$SOLANA_KEYPAIR_PATH")
RPC_URL="${SOLANA_RPC_URL:-https://api.mainnet-beta.solana.com}"

curl -s -X POST "$RPC_URL" \
  -H "Content-Type: application/json" \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"getSignaturesForAddress\",\"params\":[\"$WALLET\",{\"limit\":10}]}" | jq '.result[] | {signature: .signature, slot: .slot, blockTime: .blockTime}'
```

**Option 2: Helius (enhanced data, recommended for detailed history)**
```bash
WALLET=$(solana address --keypair "$SOLANA_KEYPAIR_PATH")

curl -s "https://api.helius.xyz/v0/addresses/${WALLET}/transactions?api-key=${HELIUS_API_KEY:-demo}&limit=10" | jq '.[] | {signature: .signature, type: .type, timestamp: .timestamp, fee: .fee}'
```

**Option 3: Shyft (free tier available)**
```bash
WALLET=$(solana address --keypair "$SOLANA_KEYPAIR_PATH")

curl -s "https://api.shyft.to/sol/v1/transaction/history?network=mainnet-beta&account=${WALLET}&tx_num=10" \
  -H "x-api-key: ${SHYFT_API_KEY}" | jq '.result.transactions'
```

**Option 4: QuickNode**
```bash
WALLET=$(solana address --keypair "$SOLANA_KEYPAIR_PATH")

curl -s -X POST "$QUICKNODE_RPC_URL" \
  -H "Content-Type: application/json" \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"getSignaturesForAddress\",\"params\":[\"$WALLET\",{\"limit\":10}]}" | jq '.result'
```

**Option 5: Alchemy**
```bash
WALLET=$(solana address --keypair "$SOLANA_KEYPAIR_PATH")

curl -s -X POST "$ALCHEMY_RPC_URL" \
  -H "Content-Type: application/json" \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"getSignaturesForAddress\",\"params\":[\"$WALLET\",{\"limit\":10}]}" | jq '.result[] | {signature: .signature, slot: .slot, blockTime: .blockTime}'
```

> 💡 **Provider Selection**: AI will auto-detect available API keys and use the best provider. If no keys configured, defaults to native Solana RPC.

### View Transaction Details

```bash
# Replace <SIGNATURE> with transaction signature
solana confirm -v <SIGNATURE>

# Or via RPC for more details
RPC_URL="${SOLANA_RPC_URL:-https://api.mainnet-beta.solana.com}"
curl -s -X POST "$RPC_URL" \
  -H "Content-Type: application/json" \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"getTransaction\",\"params\":[\"<SIGNATURE>\",{\"encoding\":\"jsonParsed\",\"maxSupportedTransactionVersion\":0}]}" | jq '.result'
```

---

## 🪙 Common Token Addresses

| Token | Symbol | Mint Address | Decimals |
|-------|--------|--------------|----------|
| Wrapped SOL | SOL | So11111111111111111111111111111111111111112 | 9 |
| USD Coin | USDC | EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v | 6 |
| Tether | USDT | Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB | 6 |
| Bonk | BONK | DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263 | 5 |
| Jupiter | JUP | JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN | 6 |
| Raydium | RAY | 4k3Dyjzvzp8eMZWUXbBCjEvwSkkk59S5iCNLY3QrkX6R | 6 |
| Pyth | PYTH | HZ1JovNiVvGrGNiiYvEozEVgZ58xaU3RKwX8eACQBCt3 | 6 |
| Jito | JTO | jtojtomepa8beP8AuQc6eXt5FriJwfFMwQx2v2f9mCL | 9 |

---

#