Solana Agent

Standard Path: CLI Tools

All tools are run from the project root. They output JSON.

Check Balance

cd /workspace/project && npx tsx tools/solana-balance.ts

Output: { "sol": 1.234, "address": "..." }

SPL token balance:

cd /workspace/project && npx tsx tools/solana-balance.ts --token USDC

Get Prices

cd /workspace/project && npx tsx tools/solana-price.ts SOL USDC BONK

Output: { "SOL": "142.35", "USDC": "1.00", "BONK": "0.00002" }

Swap Tokens

cd /workspace/project && npx tsx tools/solana-swap.ts --from SOL --to USDC --amount 0.03

Output: { "signature": "...", "status": "submitted", "inputAmount": "0.03 SOL", "outputAmount": "...", "explorer": "https://solscan.io/tx/..." }

Transfer Tokens

SOL:

cd /workspace/project && npx tsx tools/solana-transfer.ts --to <address> --amount 0.5

SPL Token:

cd /workspace/project && npx tsx tools/solana-transfer.ts --to <address> --amount 10 --token USDC

Output: { "signature": "...", "amount": "0.5 SOL", "to": "...", "explorer": "https://solscan.io/tx/..." }

Crossmint Path: MCP Tools

If signing method is crossmint, use these MCP tools instead of CLI tools:

• crossmint_get_balance — check wallet balance
• crossmint_transfer — send SOL or SPL tokens
• crossmint_sign_transaction — sign and submit a transaction

For swaps with Crossmint, get a quote from Jupiter first, then sign with crossmint_sign_transaction.

Common Tokens

The CLI tools resolve these symbols automatically. You can also pass raw mint addresses.

See tools/lib/wallet.ts for the full list of 50+ supported symbols.

Response Format

When responding to user:

Balance Check:

Balance: 1.234567 SOL
Address: 9wsmkna3YUau2oyXb62b7z373Drq2Nah1pX6WcPoqMgB

Swap:

Swap Successful

0.1 SOL -> USDC

Transaction: https://solscan.io/tx/4k2j3...abc123

Price:

SOL: $142.35
USDC: $1.00

Transfer:

Sent 0.5 SOL to 9wsmkna...

Transaction: https://solscan.io/tx/4k2j3...abc123

Error Handling

Insufficient balance: Check balance first, then inform user of available vs requested amount.

Not configured: Tell user to run npm run setup (step 10 configures Solana).

RPC error / rate limit: Retry once after a brief pause. If persistent, suggest configuring a custom RPC provider.

Installing Protocol SDKs & Creating New Tools

The tools/ directory has its own package.json and node_modules/, isolated from the host. When you need a protocol SDK that isn't already available:

1. Install it into tools/:

cd /workspace/project/tools && npm install @whatever/sdk

2. Create a new script in tools/ following the existing pattern:

cat > /workspace/project/tools/solana-my-action.ts << 'EOF'
#!/usr/bin/env npx tsx
import { loadWallet } from './lib/wallet.js';
// import from tools/node_modules — isolated deps, no version conflicts
import { SomeSDK } from '@whatever/sdk';

const { keypair, connection, publicKey } = loadWallet();
// ... build and sign transaction, output JSON
EOF

3. Run it:

cd /workspace/project && npx tsx tools/solana-my-action.ts

The tools/lib/wallet.ts helper gives you keypair, connection, publicKey, rpcUrl from the user's config. Always output JSON so results are easy to parse.

Already installed in tools/node_modules: @kamino-finance/klend-sdk, @solana/web3.js, @solana/spl-token, bs58, decimal.js

Notes

• All transactions are signed with the configured wallet
• Check balance before executing swaps/transfers
• Use devnet for testing (free SOL via airdrops)
• Mainnet operations use real SOL
• The CLI tools use Jupiter Ultra API (lite-api.jup.ag, free, no key required) for swaps/prices
• If JUPITER_API_KEY is set, tools use api.jup.ag for higher rate limits