@solana-compass/cli 0.2.0 → 0.2.2

package/skills/solana-payments-wallets-trading/references/json-output-format.md

@@ -0,0 +1,132 @@
+# JSON Output Format Reference
+
+Every Sol CLI command supports `--json` for structured output.
+
+## Response Envelope
+
+All responses use the `CommandResult<T>` envelope:
+
+```json
+{
+  "ok": true,
+  "data": { ... },
+  "meta": {
+    "elapsed_ms": 450
+  }
+}
+```
+
+### Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `ok` | `boolean` | `true` on success, `false` on failure |
+| `data` | `T` | Command-specific response data (present on success) |
+| `error` | `string` | Error code in `UPPER_SNAKE_CASE` (present on failure) |
+| `message` | `string` | Human-readable error description (present on failure) |
+| `meta` | `object` | Metadata — always includes `elapsed_ms` |
+
+## Success Response
+
+```json
+{
+  "ok": true,
+  "data": {
+    "signature": "4xK9...abc",
+    "from_token": "USDC",
+    "to_token": "BONK",
+    "from_amount": 50,
+    "to_amount": 2500000
+  },
+  "meta": { "elapsed_ms": 2100 }
+}
+```
+
+Always check `ok === true` before reading `data`.
+
+## Error Response
+
+```json
+{
+  "ok": false,
+  "error": "SWAP_FAILED",
+  "message": "Insufficient balance: need 50 USDC, have 12.5 USDC",
+  "meta": { "elapsed_ms": 150 }
+}
+```
+
+## Error Code Convention
+
+Error codes follow `NOUN_VERB_FAILED` format in `UPPER_SNAKE_CASE`:
+
+| Code | When |
+|------|------|
+| `WALLET_CREATE_FAILED` | Wallet creation fails |
+| `BALANCE_FAILED` | Balance lookup fails |
+| `SWAP_FAILED` | Token swap fails |
+| `SEND_FAILED` | Token send fails |
+| `STAKE_NEW_FAILED` | Stake creation fails |
+| `STAKE_WITHDRAW_FAILED` | Stake withdrawal fails |
+| `LEND_DEPOSIT_FAILED` | Lending deposit fails |
+| `LEND_WITHDRAW_FAILED` | Lending withdrawal fails |
+| `LEND_BORROW_FAILED` | Borrowing fails |
+| `LEND_REPAY_FAILED` | Loan repayment fails |
+| `PORTFOLIO_FETCH_FAILED` | Portfolio fetch fails |
+| `CONFIG_SET_FAILED` | Config update fails |
+| `NETWORK_FAILED` | Network info fetch fails |
+| `TOKEN_LIST_FAILED` | Token list fetch fails |
+
+## Exit Codes
+
+- `0` — Success
+- `1` — Command failed (error details in JSON response)
+
+## JSON Mode Behavior
+
+When `--json` is active:
+
+- Confirmation prompts are skipped automatically (equivalent to `--yes`)
+- Human-readable output is suppressed
+- Only the JSON envelope is printed to stdout
+- Debug/verbose output goes to stderr (if `--verbose` is also set)
+
+## Global Flags
+
+These flags work with any command:
+
+```bash
+sol <command> --json                      # structured output
+sol <command> --rpc https://my-rpc.com    # override RPC
+sol <command> --verbose                   # debug logging
+sol <command> --wallet trading            # override wallet
+```
+
+## Usage in Scripts
+
+```bash
+# Check if a swap succeeded
+result=$(sol token swap 50 usdc bonk --json)
+if echo "$result" | jq -e '.ok' > /dev/null; then
+  sig=$(echo "$result" | jq -r '.data.signature')
+  echo "Swap succeeded: $sig"
+else
+  error=$(echo "$result" | jq -r '.error')
+  echo "Swap failed: $error"
+fi
+```
+
+## Usage in Agent Code
+
+```javascript
+import { execSync } from 'node:child_process';
+
+const result = JSON.parse(
+  execSync('sol token swap 50 usdc bonk --json').toString()
+);
+
+if (result.ok) {
+  console.log(`Swapped — tx: ${result.data.signature}`);
+} else {
+  console.error(`Failed: ${result.error} — ${result.message}`);
+}
+```

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).