@solana-compass/cli 0.1.0 → 0.2.1

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

@@ -0,0 +1,174 @@
+# Lending Commands Reference
+
+Lending and borrowing on Kamino Finance.
+
+## Check Rates
+
+```bash
+sol lend rates <token>
+```
+
+Shows current deposit APY and borrow APY for a token on Kamino.
+
+### Examples
+
+```bash
+sol lend rates usdc
+sol lend rates sol
+```
+
+### JSON Output
+
+```json
+{
+  "ok": true,
+  "data": {
+    "token": "USDC",
+    "deposit_apy": "8.5%",
+    "borrow_apy": "12.3%",
+    "total_deposits": 150000000,
+    "total_borrows": 95000000,
+    "utilization": "63.3%"
+  },
+  "meta": { "elapsed_ms": 800 }
+}
+```
+
+## Deposit
+
+```bash
+sol lend deposit <amount> <token>
+```
+
+Deposits tokens into a Kamino vault to earn yield.
+
+### Examples
+
+```bash
+sol lend deposit 100 usdc
+sol lend deposit 5 sol
+sol lend deposit 100 usdc --wallet trading
+```
+
+### Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--wallet <name>` | default | Wallet to deposit from |
+
+## Withdraw
+
+```bash
+sol lend withdraw <amount|max> <token>
+```
+
+Withdraws tokens from Kamino.
+
+### Examples
+
+```bash
+sol lend withdraw 50 usdc                 # partial withdrawal
+sol lend withdraw max sol                 # withdraw everything
+sol lend withdraw max usdc --wallet defi
+```
+
+Use `max` to withdraw the entire deposited amount.
+
+### Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--wallet <name>` | default | Wallet that owns the deposit |
+
+## Borrow
+
+```bash
+sol lend borrow <amount> <token> --collateral <token>
+```
+
+Borrows tokens against deposited collateral.
+
+### Examples
+
+```bash
+sol lend borrow 500 usdc --collateral sol
+sol lend borrow 1 sol --collateral usdc
+```
+
+You must have sufficient collateral deposited first. The CLI will
+warn if the resulting health factor would be dangerously low.
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `--collateral <token>` | Required. Token to use as collateral |
+| `--wallet <name>` | Wallet that owns the collateral |
+
+## Repay
+
+```bash
+sol lend repay <amount|max> <token>
+```
+
+Repays borrowed tokens.
+
+### Examples
+
+```bash
+sol lend repay 250 usdc                   # partial repay
+sol lend repay max usdc                   # repay full outstanding debt
+```
+
+Use `max` to repay the entire borrowed amount.
+
+## View Positions
+
+```bash
+sol lend positions
+sol lend positions --wallet trading
+```
+
+Lists all deposits and borrows — token, amount, APY, USD value,
+and health factor.
+
+The CLI warns when health factor drops below 1.1.
+
+### JSON Output
+
+```json
+{
+  "ok": true,
+  "data": {
+    "deposits": [
+      {
+        "token": "USDC",
+        "amount": 100,
+        "value_usd": 100,
+        "apy": "8.5%"
+      }
+    ],
+    "borrows": [
+      {
+        "token": "USDC",
+        "amount": 50,
+        "value_usd": 50,
+        "apy": "12.3%"
+      }
+    ],
+    "health_factor": 2.1,
+    "net_value_usd": 50
+  },
+  "meta": { "elapsed_ms": 1000 }
+}
+```
+
+## Health Factor
+
+Health factor = total collateral value / total borrow value (weighted
+by liquidation thresholds). Below 1.0 means liquidation risk.
+
+- **> 2.0**: Safe
+- **1.1 – 2.0**: Monitor closely
+- **< 1.1**: CLI warns — consider repaying or adding collateral
+- **< 1.0**: Liquidation possible

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

@@ -0,0 +1,128 @@
+# Portfolio Commands Reference
+
+## View Portfolio
+
+```bash
+sol portfolio
+sol portfolio --wallet trading
+```
+
+Unified view of everything you hold — tokens, staked SOL, and lending
+positions — with USD values.
+
+### JSON Output
+
+```json
+{
+  "ok": true,
+  "data": {
+    "positions": [
+      {
+        "type": "token",
+        "symbol": "SOL",
+        "amount": 12.5,
+        "value_usd": 1878.13
+      },
+      {
+        "type": "stake",
+        "symbol": "SOL",
+        "amount": 10,
+        "value_usd": 1502.50,
+        "validator": "Comp...ass",
+        "status": "active"
+      },
+      {
+        "type": "lend",
+        "symbol": "USDC",
+        "amount": 100,
+        "value_usd": 100,
+        "protocol": "kamino",
+        "apy": "8.5%"
+      }
+    ],
+    "total_value_usd": 3480.63
+  },
+  "meta": { "elapsed_ms": 2500 }
+}
+```
+
+## Take a Snapshot
+
+```bash
+sol portfolio snapshot
+sol portfolio snapshot --label "pre-trade"
+sol portfolio snapshot --wallet trading
+```
+
+Saves the current portfolio state to SQLite for later comparison.
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `--label <text>` | Human-readable label for the snapshot |
+| `--wallet <name>` | Snapshot a specific wallet only |
+
+Snapshots include ALL position types — tokens, stakes, and lending.
+
+## List Snapshot History
+
+```bash
+sol portfolio history
+```
+
+Lists all saved snapshots with ID, timestamp, label, and total value.
+
+## Compare to a Snapshot
+
+```bash
+sol portfolio compare                     # vs latest snapshot
+sol portfolio compare 3                   # vs snapshot #3
+sol portfolio compare --wallet trading
+```
+
+Shows what changed since the snapshot — added/removed positions,
+value changes, token price movements.
+
+## Profit and Loss
+
+```bash
+sol portfolio pnl
+sol portfolio pnl --since 5              # P&L since snapshot #5
+sol portfolio pnl --wallet trading
+```
+
+Calculates profit and loss based on the transaction log and snapshots.
+The transaction log records USD prices at execution time, so cost
+basis is computed automatically.
+
+### Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--since <id>` | first snapshot | Calculate P&L from this snapshot |
+| `--wallet <name>` | all wallets | Limit to a specific wallet |
+
+## Delete a Snapshot
+
+```bash
+sol portfolio delete 3
+```
+
+Permanently removes a snapshot by ID.
+
+## Automated Snapshots
+
+```bash
+sol portfolio cron
+```
+
+Prints a crontab entry you can install to take snapshots automatically
+(e.g. daily at midnight). Useful for long-running portfolio tracking.
+
+## Tips
+
+- Take snapshots before and after significant trades to measure impact
+- Use labels to mark meaningful points ("post-rebalance", "pre-airdrop")
+- The transaction log is the source of truth for cost basis — snapshots
+  are for point-in-time comparisons

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

@@ -0,0 +1,150 @@
+# Staking Commands Reference
+
+## Create a New Stake
+
+```bash
+sol stake new <amount>
+```
+
+Creates a stake account, funds it with `<amount>` SOL, and delegates
+to a validator — all in a single transaction.
+
+### Examples
+
+```bash
+sol stake new 10                          # stake 10 SOL (default validator)
+sol stake new 5 --validator DPm...xyz     # specific validator
+sol stake new 10 --wallet cold            # from a specific wallet
+```
+
+### Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--validator <vote-address>` | Solana Compass | Validator to delegate to |
+| `--wallet <name>` | default | Wallet to fund the stake from |
+
+### JSON Output
+
+```json
+{
+  "ok": true,
+  "data": {
+    "signature": "3xY...abc",
+    "stake_account": "7gK...def",
+    "amount_sol": 10,
+    "validator": "Comp...ass"
+  },
+  "meta": { "elapsed_ms": 2500 }
+}
+```
+
+## List Stake Accounts
+
+```bash
+sol stake list
+sol stake list --wallet cold
+```
+
+Shows all stake accounts for the wallet — address, amount staked,
+validator, status (activating/active/deactivating/inactive), and
+any claimable MEV tips.
+
+Hints at `sol stake claim-mev` when tips are available.
+
+### JSON Output
+
+```json
+{
+  "ok": true,
+  "data": {
+    "stakes": [
+      {
+        "address": "7gK...def",
+        "amount_sol": 10,
+        "validator": "Comp...ass",
+        "status": "active",
+        "claimable_mev_sol": 0.05
+      }
+    ],
+    "total_staked_sol": 10,
+    "total_claimable_mev_sol": 0.05
+  },
+  "meta": { "elapsed_ms": 1200 }
+}
+```
+
+## Claim MEV Tips
+
+```bash
+sol stake claim-mev
+sol stake claim-mev --withdraw
+sol stake claim-mev 7gK...def
+```
+
+Claims MEV tips earned by your stake accounts.
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--withdraw` | false | Send tips to wallet instead of re-staking (compounding) |
+| `--wallet <name>` | default | Wallet that owns the stake accounts |
+
+By default, tips are compounded (re-staked). Use `--withdraw` to
+withdraw them to your wallet instead.
+
+You can specify a single stake account address to claim from, or
+omit it to claim from all accounts.
+
+## Withdraw / Unstake
+
+```bash
+sol stake withdraw <stake-account> [amount]
+```
+
+Withdraws SOL from a stake account. Handles the deactivation process
+automatically:
+
+- **Active stake**: Deactivates first, then you can withdraw after the
+  cooldown epoch
+- **Inactive stake**: Withdraws immediately
+- **Partially withdraw**: Specify an amount to split and withdraw
+
+### Examples
+
+```bash
+sol stake withdraw 7gK...abc              # withdraw all from this account
+sol stake withdraw 7gK...abc 5            # withdraw 5 SOL (splits if needed)
+sol stake withdraw 7gK...abc --force      # force deactivate active stake
+```
+
+### Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--wallet <name>` | default | Authority wallet |
+| `--force` | false | Force deactivation of active stake |
+
+### JSON Output
+
+```json
+{
+  "ok": true,
+  "data": {
+    "signature": "2bC...xyz",
+    "stake_account": "7gK...abc",
+    "withdrawn_sol": 10,
+    "action": "withdrawn"
+  },
+  "meta": { "elapsed_ms": 1800 }
+}
+```
+
+## Validator Selection
+
+The default validator is Solana Compass. Override with `--validator`:
+
+```bash
+sol stake new 10 --validator DPmsofDi1YBSvDJzeUSGMiHjEGkzKFKMZRiM7GYsTKcf
+```
+
+Use a vote account address (not the node identity).

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.