Solana Payments, Wallets and Trading

intent

sol is a command-line tool for working with Solana. instead of constructing transactions and managing program instructions, you describe what you want: pay someone, buy a token, stake your SOL. keys live locally on disk, never in env vars. use this skill when the user wants to send crypto, swap tokens, browse trending assets, check balances, earn yield, borrow, set up recurring buys or limit orders, provide liquidity, trade predictions, pay for APIs via x402, or view portfolio performance from the command line.

inputs

installation and setup:

• Node.js >= 20.0.0 (check with node --version)
• npx (included with modern npm)
• internet connection to reach Solana RPC endpoint

rpc endpoint (required):

• default: public Solana RPC (rate-limited, test-only)
• recommended: dedicated RPC provider (Helius, Triton, QuickNode all offer free tiers)
• env var: none required, but can be set via sol config set rpc.url <url>
• if rate limit hit: RPC calls return "429 Too Many Requests" or timeout. fallback to another provider or wait 60 seconds.

wallet(s):

• created locally in ~/.sol/wallets/ as encrypted key files
• no seed phrases stored in env vars
• can import from Solana CLI keystore
• at least 0.05 SOL recommended as gas reserve per active wallet

external connections (no API keys needed):

• Jupiter (DEX aggregator) - accessed via public RPC, no auth required
• DFlow (DeFi routing) - accessed via public RPC, no auth required
• Orca, Raydium, Meteora, Kamino (liquidity pools) - on-chain, no auth required
• Polymarket, Kalshi (prediction markets) - accessed via Jupiter, no auth required
• Kamino, MarginFi, Drift, Jupiter Lend, Loopscale (lending) - on-chain, no auth required
• all data reads cached locally after first call

configuration file:

• location: ~/.sol/config.toml
• contains: RPC URL, permissions, transaction limits, allowlists, wallet preferences
• permissions can be locked (immutable via CLI after lock) to prevent agent abuse
• filesystem access to this directory is sensitive (contains private keys and security settings)

procedure

1. initial setup

inputs: Node.js >= 20, npx, RPC endpoint URL (optional, uses public default if omitted)

steps:

a. verify Node.js version:

node --version

if output is < v20.0.0, update Node.js.

b. set RPC endpoint (optional, but recommended to avoid rate limits):

npx @solana-compass/cli@latest config set rpc.url https://your-rpc-endpoint.com

if using public RPC, skip this step. if rate limits occur during trading or staking, return here and configure a paid RPC.

c. create or list wallets:

npx @solana-compass/cli@latest wallet create --name my-wallet
npx @solana-compass/cli@latest wallet list

outputs:

• ~/.sol/config.toml created with default settings and RPC URL
• ~/.sol/wallets/my-wallet.json created (encrypted, local only)
• wallet public key printed to stdout

or shorter global install (optional):

npm install -g @solana-compass/cli
sol config set rpc.url https://your-rpc-endpoint.com
sol wallet create --name my-wallet

after global install, use sol instead of npx @solana-compass/cli@latest in all examples.

2. send payments (SOL, USDC, or any token)

inputs:

• amount (literal number, e.g., 50, not "50k")
• token symbol or mint address (e.g., "usdc", "sol", "bonk")
• recipient wallet address (full base58 public key, no .sol domains or SNS)
• optional: source wallet name (defaults to configured default wallet)
• optional: --yes flag to skip confirmation

steps:

a. verify recipient address is correct:

sol wallet list
# copy target address from output

b. send payment:

sol token send 50 usdc GkX...abc
sol token send 2 sol 7nY...xyz
sol token send 1000 bonk AgE...def --yes

c. confirm transaction printed to stdout includes recipient, amount, fee (usually 0.000005 SOL), and transaction signature.

outputs:

• transaction signature on stdout
• updated wallet balance in human-readable format
• cost basis recorded in transaction log for P&L tracking

transaction log:

• stored in ~/.sol/transactions.log (human-readable, includes USD price at execution time)

3. discover and browse tokens

inputs: optional category filter or limit

steps:

a. browse trending tokens:

sol token browse trending

b. browse by category (top-traded in last 24h, recently launched, liquid staking tokens, etc.):

sol token browse top-traded --interval 24h
sol token browse recent --limit 10
sol token browse lst

c. results print as table with symbol, mint, price, 24h volume, creator, launch date.

d. to get more details on a specific token:

sol token info bonk
sol token price bonk

outputs:

• formatted table of tokens with symbol, mint, price, volume, APY (if applicable)
• results cached locally, so follow-up token info and token price calls resolve instantly
• token mint address printed, copyable for explicit swaps

edge case: if a symbol maps to multiple tokens (e.g., "shib" on Solana and Ethereum), CLI picks the highest-liquidity match on Jupiter without prompting. to verify, run sol token info <symbol> before trading.

4. swap tokens (buy or sell)

inputs:

• amount (literal number)
• input token (symbol or mint)
• output token (symbol or mint)
• optional: --quote-only to preview without executing
• optional: --router jupiter or --router dflow to force a specific DEX aggregator
• optional: --slippage <percent> (default 1%)
• optional: --wallet <name> to use a specific wallet

steps:

a. preview the swap without executing (recommended):

sol token swap 50 usdc bonk --quote-only

output shows input amount, output amount, price impact, and estimated fee.

b. if price looks good, execute:

sol token swap 50 usdc bonk

or skip preview and execute directly.

c. confirm transaction signature and updated balances printed.

outputs:

• transaction signature
• exact output amount received
• fee (usually 0.000005 SOL plus DEX fee)
• swap price and slippage recorded in transaction log with USD value at execution

edge cases:

• if slippage exceeds limit, swap fails. increase --slippage or try again later if token is volatile.
• if balance is insufficient, error printed. check sol wallet balance.
• if output token has no liquidity route to input token, "no route found" error. try swapping through an intermediate token (e.g., SOL).
• if one or both tokens cannot be resolved (ambiguous symbol, dead mint), error printed with suggestions. use mint address to disambiguate.

5. set up dollar-cost averaging (DCA)

inputs:

• total amount in USDC (minimum $100)
• target token (symbol or mint)
• interval (minute, hour, day, week, month)
• order count (minimum 2)
• each order is total divided by count (minimum $50 per order)
• optional: --wallet <name>

steps:

a. create a DCA order that buys target token automatically:

sol token dca new 500 usdc sol --every day --count 10

this creates 10 orders of 50 USDC each, one per day.

b. list active DCA orders:

sol token dca list

output shows order key, target token, remaining orders, next execution time.

c. if conditions change, cancel:

sol token dca cancel <orderKey>

outputs:

• order key (use to cancel)
• execution schedule printed
• each execution recorded in transaction log with USD price

constraints:

• minimum total $100, minimum order count 2, minimum per-order $50
• intervals: minute (every 60 seconds), hour, day, week, month
• if next execution time passes and wallet has insufficient balance, order skips that execution and retries next interval
• locked capital (remaining order amount) appears in sol portfolio to show what's reserved

6. set up limit orders

inputs:

• amount (literal number)
• input token (symbol or mint)
• output token (symbol or mint)
• target price (--at <price>)
• optional: --quote-only to preview
• optional: --wallet <name>

steps:

a. preview the order without placing it:

sol token limit new 50 usdc bonk --at 0.000003 --quote-only

output shows order details and number of output tokens if executed at target price.

b. place the order:

sol token limit new 50 usdc bonk --at 0.000003

c. list active orders:

sol token limit list

shows order key, input/output tokens, target price, fill status.

d. cancel if price moves past target:

sol token limit cancel <orderKey>

outputs:

• order key (use to cancel or look up)
• limit price and current price compared
• locked capital appears in sol portfolio as "pending limit orders"
• when target is hit, order fills automatically and swap recorded in transaction log

edge case: if price drops below target and order hasn't filled, it remains active indefinitely (or until cancelled). if price spikes above target without triggering, check on-chain liquidity or try a price closer to market.

7. check balances and list tokens

inputs: optional wallet name (defaults to default wallet)

steps:

a. check all token balances with USD value:

sol wallet balance
sol wallet balance trading

output is formatted table with token, amount, USD value.

b. list only token balances (no USD conversion):

sol token list

c. list all local wallets:

sol wallet list

output shows wallet names, public keys, and flags (default, read-only).

outputs:

• formatted table with symbol, amount, USD value
• total portfolio USD value at bottom
• USD prices fetched from Jupiter and cached

8. create and manage wallets

inputs: optional wallet name (auto-generated if omitted)

steps:

a. create a new wallet:

sol wallet create
sol wallet create --name trading

output shows new public key and wallet name.

b. import from Solana CLI keystore:

sol wallet import --solana-cli

prompts for keypair path, imports and stores in ~/.sol/wallets/.

c. set a wallet as default for future commands:

sol wallet set-default trading

or use --wallet <name> on any command to target a specific wallet.

d. see transaction history for a wallet:

sol wallet history trading

outputs:

• wallet public key
• wallet name stored in ~/.sol/config.toml
• private key encrypted and stored in ~/.sol/wallets/<name>.json
• never printed to stdout or env vars

security:

• keys are encrypted at rest with a passphrase or local key derivation
• agent tools cannot read raw key material without explicitly opening ~/.sol/wallets/ files
• recommend: use dedicated wallets with limited funds for agent-driven workflows

9. stake SOL

inputs:

• amount in SOL (literal number, e.g., 10)
• optional: validator public key (defaults to validator with lowest commission)
• optional: --wallet <name>

steps:

a. stake SOL with default validator:

sol stake new 10

creates a new stake account, funds it, and delegates to validator. transaction shows account address.

b. list all stake accounts and claimable MEV:

sol stake list

output shows stake account pubkey, amount, validator, activation status, APY, claimable MEV rewards.

c. claim MEV rewards and compound (reinvest into stake):

sol stake claim-mev

transfers rewards to active stake account balance. if you want to keep rewards separate, withdraw and re-stake manually.

d. unstake (withdraw SOL):

sol stake withdraw 7gK...abc

input is stake account pubkey (from sol stake list). begins unstaking immediately; SOL is claimable after next epoch (about 2-3 days).

outputs:

• stake account pubkey (use for future withdrawals)
• transaction signature
• staking APY and earned rewards printed
• MEV balance shown separately

edge case: if you unstake mid-epoch, rewards are forfeited for that epoch. claim MEV before unstaking if rewards are significant.

10. earn yield by lending

inputs:

• token (symbol or mint, e.g., "usdc", "sol")
• amount (literal number for deposits/borrows)
• optional: --protocol <name> to target specific protocol (kamino, marginfi, drift, jupiter-lend, loopscale)
• optional: --wallet <name>

steps:

a. compare lending rates across all protocols:

sol lend rates usdc
sol lend rates sol

output is table with protocol, deposit APY, borrow APY, TVL.

b. deposit to earn yield (auto-picks highest rate unless protocol specified):

sol lend deposit 100 usdc
sol lend deposit 5 sol --protocol kamino

transaction signature and current balance printed.

c. borrow against collateral:

sol lend borrow 500 usdc --collateral sol

deposits SOL as collateral, borrows USDC. output shows collateral ratio and liquidation price.

d. see all lending positions across protocols:

sol lend positions

table shows protocol, token, amount, APY, earned interest, collateral posted.

e. repay a borrow:

sol lend repay 100 usdc

f. withdraw a deposit:

sol lend withdraw 50 usdc --protocol kamino

outputs:

• transaction signature
• updated deposit balance and earned interest
• collateral ratio and liquidation price (if borrowed)
• all positions appear in sol portfolio alongside tokens and stakes

edge case: if collateral ratio drops below protocol minimum due to market moves, position enters liquidation. borrow less or add more collateral to stay safe. monitor sol portfolio and sol lend positions regularly.

11. earn yield in vaults (managed strategy)

inputs:

• token (symbol or mint, e.g., "usdc", "sol")
• amount (literal number)
• optional: --protocol <name> to target specific vault provider (kamino-earn, loopscale)
• optional: --vault <name> to target specific vault (use from sol earn <token> output)

steps:

a. list available vaults for a token, sorted by APY:

sol earn usdc
sol earn sol
sol earn

output shows protocol, vault name, token, current APY, TVL, strategy description.

b. deposit to highest-APY vault (auto-selected):

sol earn deposit 100 usdc

or target specific protocol:

sol earn deposit 5 sol --protocol kamino

c. see all vault positions across protocols:

sol earn positions

table shows vault name, token, balance, current APY, earned interest.

d. withdraw from a vault (partial or full):

sol earn withdraw 50 usdc
sol earn withdraw max usdc --protocol loopscale

outputs:

• transaction signature
• updated vault balance and earned interest
• all positions appear in sol portfolio alongside tokens, staking, and lending

difference from lending:

• vaults are managed strategies (Kamino Earn, Loopscale) that automatically optimize yields
• lending is raw deposits earning fixed APY on protocols (Kamino, MarginFi, Drift, etc.)
• vault APYs often higher but depend on strategy performance; lending APYs more stable

12. provide liquidity (AMM pools)

inputs:

• token pair (e.g., "sol usdc")
• amount and price range (for concentrated liquidity)
• optional: pool ID or DEX filter (orca, raydium, meteora, kamino)
• optional: --sort apy or --sort volume to prioritize pools
• optional: --wallet <name>

steps:

a. browse pools by pair:

sol lp pools sol usdc

output is table with DEX, pair, TVL, APY, 24h volume, fee tier.

b. filter by APY or type (concentrated vs. constant product):

sol lp pools --sort apy --type clmm

c. deposit liquidity with price range:

sol lp deposit HJPj...abc 100 usdc --range 10

input is pool ID (from sol lp pools output), amount, and range in percent (e.g., +/-10% around current price). transaction shows LP token address.

d. see all LP positions with P&L and impermanent loss:

sol lp positions

table shows pool, your liquidity amount, earned fees, impermanent loss, APY realized.

e. claim unclaimed fees:

sol lp claim 9xK...abc

input is LP token address. fees withdrawn to wallet.

f. withdraw liquidity:

sol lp withdraw 9xK...abc

removes all liquidity and claims fees. returns your tokens and earned fees.

outputs:

• LP token address (use for future claims/withdrawals)
• transaction signature
• current position value and fees earned
• impermanent loss calculated and shown

advanced:

• farm for rewards: sol lp farm stake <pool-id> to lock LP tokens and earn additional incentives
• create new pool: sol lp create <token1> <token2> --fee 0.3 (requires canLend permission)
• see farming rewards: sol lp farm list

edge case: concentrated liquidity (clmm) pools can incur impermanent loss if price moves far from your range. if price moves outside range, your liquidity stops earning fees. adjust range or withdraw and re-deposit at new price.

13. trade prediction markets

inputs:

• market category or event search
• prediction (buy/sell yes/no contracts)
• optional: position to close or settle

steps:

a. browse prediction markets by category:

sol predict list crypto
sol predict list sports
sol predict list politics

output shows category, event title, resolution date, available markets.

b. search for specific events:

sol predict search "solana"

c. see details of an event:

sol predict event POLY-89525

output shows markets within that event (e.g., "will price exceed $X?"), current prices, orderbook depth.

d. check a specific market:

sol predict market POLY-701571

shows bid/ask prices, volume, open interest.

e. buy contracts (e.g., "yes" for an outcome):

sol predict buy 5 yes POLY-701571

purchases 5 YES contracts at current ask price. transaction shows cost in USDC.

f. see all open positions:

sol predict positions

table shows market, contracts owned (yes/no), entry price, current price, unrealized P&L.

g. sell a position to close:

sol predict sell <positionPubkey>

h. claim resolved winnings:

sol predict claim <positionPubkey>

i. see transaction history:

sol predict history

outputs:

• transaction signature for buys/sells
• contract quantity and price paid
• position unrealized P&L
• all positions appear in sol portfolio with profit/loss summary

edge case: markets resolve on specific dates. if market is unresolved, you cannot claim. check event date before buying. if market moves against you, selling at a loss is possible; orders executed immediately at current market price.

14. pay for APIs with x402

inputs:

• URL (https://api.example.com/data)
• optional: HTTP method, headers, body (curl-like syntax)
• optional: --dry-run to show cost without paying
• optional: --max <usdc> to set spending cap

steps:

a. fetch a URL that requires x402 payment:

sol fetch https://api.example.com/data

if server returns 402 Payment Required, CLI signs a USDC transfer, attaches it, and retries. response body printed to stdout, payment info to stderr.

b. preview cost without paying:

sol fetch https://api.example.com/data --dry-run

output shows price in USDC and what would be sent.

c. set a spending cap:

sol fetch https://api.example.com/data --max 0.05

if server asks for more than 0.05 USDC, request fails. prevents overpaying for data.

d. POST with headers:

sol fetch https://api.example.com/rpc \
  -X POST -d '{"query":"..."}' \
  -H "Accept: application/json"

curl-like syntax supported. response body is JSON or text, printed to stdout.

outputs:

• response body on stdout (pipe-friendly)
• payment info on stderr (amount, server, wallet)
• transaction signature of payment on-chain
• cost recorded in transaction log

edge cases:

• if server doesn't support x402, regular HTTP response returned
• if server asks for more than --max, request fails and no payment sent
• if wallet has insufficient USDC balance, payment fails with balance error
• timeouts (>30s) fail with timeout error. data may have been fetched but payment not signed. check server logs.
• payments are non-reversible once on-chain; don't set --max too high

15. track portfolio performance

inputs: none required

steps:

a. see full portfolio snapshot (tokens, staking, lending, LP, open orders):

sol portfolio

output shows all positions with current balances, USD values, and total net worth.

b. compare portfolio to previous snapshot:

sol portfolio compare

shows what changed since last view (buys, sells, price moves, interest earned).

c. see profit/loss over time:

sol portfolio pnl

table shows realized gains/losses from closed trades, unrealized gains from open positions, interest earned, fees paid.

outputs:

• formatted table with position type (token, stake, lend, LP, order), amount, USD value, change
• total portfolio value and period return percentage
• snapshots auto-saved every 5 minutes (rate-limited, so portfolio compare always has recent reference data)
• active DCA and limit orders shown with fill progress and locked capital

edge case: if portfolio has not been viewed twice, portfolio compare returns "no previous snapshot." run again later.

16. view structured output (JSON)

inputs: any command with --json flag

steps:

a. append --json to any command:

sol wallet balance --json
sol token swap 50 usdc bonk --json
sol portfolio --json

outputs:

• CommandResult envelope with structure:

{
  "ok": true,
  "data": { ... command-specific payload ... },
  "meta": {
    "elapsed_ms": 450,
    "rpc_calls": 3,
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

use cases:

• scripting and automation (parse JSON in bash, Python, etc.)
• agent workflows (structured data for downstream decisions)
• debugging (meta includes RPC call count and timing)

17. network and transaction utilities

inputs: optional transaction signature

steps:

a. check network status (epoch, TPS, staking APY):

sol network

output shows current epoch, slots/second, average staking APY, SOL price.

b. look up any transaction:

sol tx 4xK9...abc

input is transaction signature. output shows sender, recipient(s), tokens, amounts, status (success/failed), block height.

outputs:

• network statistics printed as key-value pairs
• transaction details with all transfers and account changes shown

18. configure RPC endpoint

inputs: RPC URL (https://... or ws://...)

steps:

a. change RPC endpoint:

sol config set rpc.url https://your-rpc-endpoint.com

b. verify current RPC: