@solana-compass/cli 0.2.0 → 0.2.2

package/skills/solana-payments-wallets-trading/references/trading-commands.md

@@ -0,0 +1,207 @@
+# Trading Commands Reference
+
+## Swap Tokens
+
+```bash
+sol token swap <amount> <from> <to>
+```
+
+Swaps tokens via Jupiter aggregator — best price across all Solana DEXes.
+
+### Examples
+
+```bash
+sol token swap 50 usdc bonk               # buy BONK with USDC
+sol token swap 1.5 sol usdc               # sell SOL for USDC
+sol token swap 100 usdc sol --wallet bot   # from a specific wallet
+sol token swap 50 usdc bonk --quote-only   # preview without executing
+sol token swap 50 usdc bonk --slippage 100 # 1% slippage (100 bps)
+sol token swap 50 usdc bonk --yes          # skip confirmation
+```
+
+### Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--slippage <bps>` | 50 | Slippage tolerance in basis points (50 = 0.5%) |
+| `--quote-only` | false | Show quote without executing |
+| `--wallet <name>` | default | Wallet to swap from |
+| `--yes` | false | Skip confirmation prompt |
+
+### Token Resolution
+
+Tokens can be specified by symbol (`sol`, `usdc`, `bonk`) or mint
+address. Resolution order:
+
+1. Hardcoded well-known list (SOL, USDC, USDT, JUP, BONK, mSOL,
+   jitoSOL, bSOL, ETH, wBTC, PYTH, JTO, WEN, RNDR, JLP)
+2. Local SQLite cache (24-hour TTL)
+3. Jupiter Token API (ranked by liquidity)
+
+For safety with unfamiliar tokens, verify with `sol token info <symbol>`
+first, or use the mint address directly.
+
+### JSON Output
+
+```json
+{
+  "ok": true,
+  "data": {
+    "signature": "4xK9...abc",
+    "from_token": "USDC",
+    "from_amount": 50,
+    "to_token": "BONK",
+    "to_amount": 2500000,
+    "price_impact": "0.01%",
+    "from_price_usd": 1.0,
+    "to_price_usd": 0.00002
+  },
+  "meta": { "elapsed_ms": 2100 }
+}
+```
+
+## Send Tokens
+
+```bash
+sol token send <amount> <token> <recipient>
+```
+
+Send SOL or any SPL token to a wallet address.
+
+### Examples
+
+```bash
+sol token send 2 sol 7nY...xyz
+sol token send 50 usdc GkX...abc
+sol token send 1000 bonk AgE...def --yes
+sol token send 0.5 sol 7nY...xyz --wallet trading
+```
+
+### Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--wallet <name>` | default | Wallet to send from |
+| `--yes` | false | Skip confirmation prompt |
+
+In `--json` mode, confirmations are always skipped.
+
+### JSON Output
+
+```json
+{
+  "ok": true,
+  "data": {
+    "signature": "5aB...xyz",
+    "token": "USDC",
+    "amount": 50,
+    "recipient": "GkX...abc",
+    "price_usd": 1.0
+  },
+  "meta": { "elapsed_ms": 1500 }
+}
+```
+
+## Check Prices
+
+```bash
+sol token price <symbols...>
+```
+
+### Examples
+
+```bash
+sol token price sol                       # single token
+sol token price sol usdc bonk eth         # multiple at once
+```
+
+Prices come from Jupiter Price API with CoinGecko fallback.
+
+### JSON Output
+
+```json
+{
+  "ok": true,
+  "data": {
+    "prices": [
+      { "symbol": "SOL", "price_usd": 150.25, "mint": "So11...1112" }
+    ]
+  },
+  "meta": { "elapsed_ms": 200 }
+}
+```
+
+## Token Info
+
+```bash
+sol token info <symbol>
+```
+
+Shows token metadata — mint address, decimals, total supply. Useful
+for verifying which token a symbol resolves to before transacting.
+
+## List Tokens
+
+```bash
+sol token list                            # default wallet
+sol token list --wallet trading           # specific wallet
+```
+
+Lists all tokens held in the wallet with balances and USD values.
+
+## Burn Tokens
+
+```bash
+sol token burn <symbol> [amount]
+```
+
+### Examples
+
+```bash
+sol token burn bonk 1000                  # burn specific amount
+sol token burn bonk --all                 # burn entire balance
+sol token burn bonk --all --close         # burn and close the account
+```
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `--all` | Burn entire balance |
+| `--close` | Close the token account after burning (reclaims ~0.002 SOL rent) |
+| `--wallet <name>` | Wallet to burn from |
+| `--yes` | Skip confirmation |
+
+## Close Token Accounts
+
+```bash
+sol token close [symbol]
+```
+
+Closes empty token accounts and reclaims rent (~0.002 SOL each).
+
+### Examples
+
+```bash
+sol token close usdc                      # close specific account
+sol token close --all --yes               # close all empty accounts
+sol token close --all --burn --yes        # burn dust + close all
+```
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `--all` | Close all eligible accounts |
+| `--burn` | Burn remaining dust before closing |
+| `--wallet <name>` | Wallet to close accounts in |
+| `--yes` | Skip confirmation |
+
+## Sync Token Cache
+
+```bash
+sol token sync
+```
+
+Refreshes the local token metadata cache from Jupiter's token list.
+Normally not needed — tokens are cached on first use.

package/skills/solana-payments-wallets-trading/references/troubleshooting.md

@@ -0,0 +1,158 @@
+# Troubleshooting
+
+## RPC Issues
+
+### "Rate limited" or slow responses
+
+The public Solana RPC (`api.mainnet-beta.solana.com`) rate-limits
+aggressively. Set a dedicated RPC endpoint:
+
+```bash
+sol config set rpc.url https://your-rpc-endpoint.com
+```
+
+Free RPC tiers are available from Helius, Triton, and QuickNode.
+
+### RPC resolution order
+
+The CLI finds an RPC endpoint in this order:
+
+1. `--rpc` flag on the command
+2. `SOL_RPC_URL` environment variable
+3. `~/.sol/config.toml` → `rpc.url`
+4. Solana CLI config (`solana config get`)
+5. Public mainnet RPC (with warning)
+
+### "Failed to fetch blockhash" / connection errors
+
+- Check that your RPC URL is correct: `sol config get rpc.url`
+- Verify the endpoint is reachable: `curl <your-rpc-url> -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"getHealth"}'`
+- Try a different RPC provider
+
+## Token Resolution
+
+### Wrong token resolved
+
+Symbol search is ranked by liquidity, but ambiguous symbols can
+resolve to the wrong token. To verify:
+
+```bash
+sol token info <symbol>       # check the mint address
+```
+
+To avoid ambiguity, use the mint address directly:
+
+```bash
+sol token swap 50 usdc EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
+```
+
+### "Token not found"
+
+- Run `sol token sync` to refresh the local cache
+- Use the full mint address instead of a symbol
+- Check if the token exists on Jupiter: some very new or illiquid
+  tokens may not be indexed yet
+
+## Transaction Issues
+
+### "Transaction simulation failed"
+
+Common causes:
+- **Insufficient balance**: Check with `sol wallet balance`
+- **Slippage exceeded**: Increase with `--slippage <bps>` (e.g. `--slippage 200` for 2%)
+- **Account not initialized**: The CLI creates associated token accounts
+  automatically, but some edge cases may require manual setup
+
+### "Transaction expired"
+
+Solana transactions have a ~60-second lifetime. This can happen when:
+- The RPC is slow to relay the transaction
+- Network congestion is high
+
+The CLI retries automatically with backoff. If it keeps failing, try
+again or use a faster RPC endpoint.
+
+### "Blockhash not found"
+
+Usually means the transaction took too long to confirm. The CLI
+handles retry logic, but persistent failures suggest RPC issues.
+
+## Wallet Issues
+
+### "No wallets found"
+
+Create one:
+
+```bash
+sol wallet create --name main
+```
+
+Or import from Solana CLI:
+
+```bash
+sol wallet import --solana-cli
+```
+
+### "Wallet not found: <name>"
+
+Check available wallets:
+
+```bash
+sol wallet list
+```
+
+Wallet names are case-sensitive.
+
+### Recovering a removed wallet
+
+`sol wallet remove` renames the key file to `<name>.json.deleted` in
+`~/.sol/wallets/`. To recover, rename it back:
+
+```bash
+mv ~/.sol/wallets/old-wallet.json.deleted ~/.sol/wallets/old-wallet.json
+```
+
+Then re-import it:
+
+```bash
+sol wallet import ~/.sol/wallets/old-wallet.json --name old-wallet
+```
+
+## Staking Issues
+
+### "Stake account is activating"
+
+New stakes take 1 epoch (~2-3 days) to become active. During this
+time, the account shows as "activating" and cannot be withdrawn.
+
+### "Cannot withdraw active stake"
+
+Active stake must be deactivated first. Use `--force` to deactivate:
+
+```bash
+sol stake withdraw 7gK...abc --force
+```
+
+After deactivation, wait one epoch for it to become inactive, then
+withdraw.
+
+## Database Issues
+
+### Corrupted database
+
+The SQLite database is at `~/.sol/data.db`. If it becomes corrupted:
+
+```bash
+rm ~/.sol/data.db
+```
+
+The CLI will recreate it on next run. You'll lose transaction history
+and snapshots, but wallet key files are stored separately and are
+not affected.
+
+## General Tips
+
+- Use `--verbose` on any command to see debug output
+- Use `--json` to get structured error messages with error codes
+- Check `sol config list` to verify your settings
+- Run `sol network` to verify RPC connectivity and see network status

package/skills/solana-payments-wallets-trading/references/wallet-commands.md

@@ -0,0 +1,152 @@
+# Wallet Commands Reference
+
+## Create a Wallet
+
+```bash
+sol wallet create                         # auto-named (wallet-1, wallet-2, ...)
+sol wallet create --name trading          # pick a name
+sol wallet create --name bot --count 5    # batch-create 5 wallets
+```
+
+Creates a new Ed25519 keypair and stores it as a JSON key file in
+`~/.sol/wallets/<name>.json` (Solana CLI compatible format, chmod 600).
+
+The first wallet created becomes the default for all commands.
+
+## List Wallets
+
+```bash
+sol wallet list                           # all wallets with SOL balances
+sol wallet list --label trading           # filter by label
+```
+
+Shows wallet name, address, SOL balance, and whether it's the default.
+Hints at `sol wallet balance <name>` for full token breakdown.
+
+## Check Balances
+
+```bash
+sol wallet balance                        # default wallet, all tokens + USD
+sol wallet balance trading                # specific wallet
+```
+
+Displays every token held with current USD values. Tokens below the
+dust threshold ($0.0001) are grouped as dust.
+
+## Import an Existing Wallet
+
+```bash
+sol wallet import --solana-cli            # from ~/.config/solana/id.json
+sol wallet import ./keypair.json --name cold
+sol wallet import /path/to/key.json
+```
+
+Copies the key file into `~/.sol/wallets/`. The `--solana-cli` flag
+imports from the default Solana CLI keypair location.
+
+## Export / Show Key File Path
+
+```bash
+sol wallet export main
+```
+
+Prints the file system path to the key file. Does NOT print the
+private key itself.
+
+## Remove a Wallet
+
+```bash
+sol wallet remove old-wallet
+```
+
+Removes the wallet from the registry. The key file is renamed with a
+`.deleted` suffix (not permanently deleted) so it can be recovered.
+
+## Set Default Wallet
+
+```bash
+sol wallet set-default trading
+```
+
+Changes which wallet is used when `--wallet` is not specified.
+
+## Labels
+
+```bash
+sol wallet label main --add trading       # add a label
+sol wallet label main --add defi --add bot  # multiple labels
+sol wallet label main --remove trading    # remove a label
+```
+
+Labels are freeform tags for organizing wallets. Use them with
+`sol wallet list --label <label>` to filter.
+
+## Transaction History
+
+```bash
+sol wallet history                        # recent transactions
+sol wallet history --limit 20            # more results
+sol wallet history --type swap           # filter by type (swap, send, stake, lend)
+sol wallet history trading               # specific wallet
+```
+
+Shows transactions from the local log — type, tokens, amounts, USD
+values at execution time, and timestamps.
+
+## Fund via Fiat Onramp
+
+```bash
+sol wallet fund                          # default wallet, default amount
+sol wallet fund --amount 50              # specify USD amount
+sol wallet fund trading --provider moonpay
+```
+
+Generates a URL to purchase SOL via a fiat onramp provider. Opens
+in your browser.
+
+## Wallet Flag
+
+Any command accepts `--wallet <name>` to override the default wallet:
+
+```bash
+sol wallet balance --wallet trading
+sol token swap 50 usdc bonk --wallet trading
+sol stake new 10 --wallet cold
+sol lend deposit 100 usdc --wallet defi
+sol portfolio --wallet trading
+```
+
+## JSON Output
+
+All wallet commands support `--json`:
+
+```bash
+sol wallet list --json
+sol wallet balance --json
+```
+
+### Example: `sol wallet list --json`
+
+```json
+{
+  "ok": true,
+  "data": {
+    "wallets": [
+      {
+        "name": "main",
+        "address": "7nY...xyz",
+        "sol_balance": 12.5,
+        "is_default": true,
+        "labels": ["trading"]
+      }
+    ]
+  },
+  "meta": { "elapsed_ms": 320 }
+}
+```
+
+## Data Storage
+
+- Key files: `~/.sol/wallets/<name>.json`
+- Wallet registry: `~/.sol/data.db` (SQLite)
+- Config: `~/.sol/config.toml`