@solana-compass/cli 0.1.0 → 0.2.1

package/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "solana-payments-wallets-trading",
+  "description": "Pay people in SOL or USDC, buy and sell tokens, manage wallets, stake, lend, and track your Solana portfolio. No API keys needed.",
+  "version": "0.2.0",
+  "author": "solanaguide"
+}

package/README.md

@@ -1,37 +1,31 @@
 # sol — Solana for Humans and LLM Agents
 
-A Solana CLI that reads like English. Every command has structured `--json` output so LLM agents like Claude Code can drive it programmatically — managing wallets, executing swaps, staking, lending, and tracking portfolios without ever touching raw transactions.
+A command-line tool that lets you work with Solana the way you'd describe it out loud. Pay people, buy and sell tokens, stake, lend, and track your portfolio — instead of constructing transactions and managing program instructions, you say what you want. Keys live locally on disk. No API keys, no private key env vars.
 
 ```bash
-sol token swap 50 usdc bonk          # Swap via Jupiter
-sol stake new 10                      # Stake SOL in one command
-sol lend deposit 100 usdc             # Earn yield on Kamino
-sol portfolio                         # See everything you hold
-```
+# Set up
+sol wallet create --name "ClawdBot"
 
----
+# Transfer some SOL to the agent wallet, then:
 
-## Why This Exists
+# Check balance
+sol wallet balance
 
-Solana has great infrastructure but terrible UX for automation. An LLM agent that wants to "swap 50 USDC for BONK" shouldn't need to construct transaction messages, manage blockhashes, or parse binary account data. **sol** wraps all of that behind natural-language commands with structured JSON responses:
+# Swap 50 USDC for BONK
+sol token swap 50 usdc bonk
 
-```bash
-$ sol token swap 50 usdc bonk --json
-{
-  "ok": true,
-  "data": {
-    "inputToken": "USDC",
-    "outputToken": "BONK",
-    "inputAmount": 50,
-    "outputAmount": 3842519.52,
-    "signature": "4xK9...",
-    "explorerUrl": "https://solscan.io/tx/4xK9..."
-  },
-  "meta": { "elapsed_ms": 1823 }
-}
-```
+# Stake idle SOL
+sol stake new 10
 
-No API keys required. No SDK integration. Just commands and JSON.
+# Deposit USDC to earn yield on Kamino
+sol lend deposit 100 usdc
+
+# See everything you hold
+sol portfolio
+
+# Snapshot for tracking over time
+sol portfolio snapshot --label "post-rebalance"
+```
 
 ---
 
@@ -49,6 +43,20 @@ npx @solana-compass/cli wallet list
 
 Requires Node.js >= 20.
 
+### Install as an Agent Skill
+
+Sol CLI is available as a discoverable skill for Claude Code and other LLM agents:
+
+```bash
+# Claude Code plugin marketplace
+/plugin marketplace add solanaguide/solana-cli
+
+# skills.sh
+npx skills add solanaguide/solana-cli
+```
+
+Once installed, the agent can use Sol commands directly when you ask it to send crypto, trade tokens, check balances, stake, lend, or track portfolio performance.
+
 ### First-time setup
 
 ```bash
@@ -80,7 +88,6 @@ sol wallet set-default trading                 # Change the active wallet
 sol wallet label main --add trading           # Tag wallets for organization
 sol wallet history                            # Recent transaction activity
 sol wallet history --type swap --limit 5      # Filtered
-sol wallet fund --amount 100                  # Generate fiat onramp URL (Transak)
 ```
 
 Wallets are stored locally as key files. The first wallet created becomes the default for all commands. Change it with `sol wallet set-default <name>`, or override per-command with `--wallet <name-or-address>`.
@@ -194,11 +201,10 @@ sol tx 4xK9...abc                             # Look up a transaction by signatu
 
 ---
 
-## For LLM Agents
+## Structured Output
 
-Every command supports `--json` for structured output. Responses follow a consistent envelope:
+Every command supports `--json` for automation and scripting:
 
-**Success:**
 ```json
 {
   "ok": true,
@@ -207,50 +213,7 @@ Every command supports `--json` for structured output. Responses follow a consis
 }
 ```
 
-**Error:**
-```json
-{
-  "ok": false,
-  "error": "SWAP_FAILED",
-  "message": "Insufficient SOL balance"
-}
-```
-
-Error codes are predictable `UPPER_SNAKE_CASE` identifiers (`WALLET_CREATE_FAILED`, `LEND_DEPOSIT_FAILED`, etc.). An agent can branch on `ok`, read `data` for results, and use `error` codes for programmatic error handling without parsing human text.
-
-### Agent workflow example
-
-A Claude Code agent managing a DeFi portfolio might run:
-
-```bash
-# 1. Check what we're working with
-sol wallet balance --json
-sol portfolio --json
-
-# 2. Sell some BONK for USDC
-sol token swap 1000000 bonk usdc --json
-
-# 3. Put idle USDC to work earning yield
-sol lend deposit 100 usdc --json
-
-# 4. Stake idle SOL
-sol stake new 5 --json
-
-# 5. Verify final state and snapshot for tracking
-sol portfolio --json
-sol portfolio snapshot --label "rebalanced" --json
-```
-
-Each step returns structured data the agent can parse and act on. No web scraping, no API key management, no transaction construction.
-
-### What agents get for free
-
-- **Wallet management** — Create and fund wallets without touching key files
-- **Token resolution** — Say `sol` or `usdc` instead of mint addresses
-- **Transaction handling** — Automatic retries, blockhash management, confirmation polling
-- **Cost-basis tracking** — Every swap is logged with USD prices at execution time
-- **Portfolio snapshots** — Track P&L across sessions without external databases
-- **Error classification** — Structured errors distinguish transient failures (retry) from terminal ones (stop)
+Error codes are predictable `UPPER_SNAKE_CASE` identifiers (`SWAP_FAILED`, `LEND_DEPOSIT_FAILED`, etc.).
 
 ---
 
@@ -259,11 +222,10 @@ Each step returns structured data the agent can parse and act on. No web scrapin
 | Flag | Description |
 |------|-------------|
 | `--json` | Structured JSON output |
-| `--wallet <name>` | Override default wallet |
 | `--rpc <url>` | Override RPC endpoint |
 | `--verbose` | Show debug logging |
 
-These work on every command: `sol --json --wallet trading token swap 50 usdc bonk`
+Most commands also accept `--wallet <name-or-address>` to override the default wallet.
 
 ## RPC Resolution
 
@@ -291,7 +253,7 @@ The transaction log is the source of truth for cost basis and P&L — every swap
 
 ## Architecture
 
-- **Runtime**: Node.js via `tsx` — no build step needed
+- **Runtime**: Node.js (compiled from TypeScript)
 - **CLI framework**: commander.js
 - **Solana SDK**: `@solana/kit` v2
 - **Swaps**: Jupiter REST API (no SDK, no API key)

package/bin/sol.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-await import(join(__dirname, '..', 'dist', 'index.js'));
+await import(pathToFileURL(join(__dirname, '..', 'dist', 'index.js')).href);

package/dist/index.js

@@ -14,7 +14,7 @@ const program = new Command();
 program
     .name('sol')
     .description('Solana CLI for Humans and LLM Agents')
-    .version('0.1.0')
+    .version('0.2.0')
     .option('--json', 'Output structured JSON')
     .option('--rpc <url>', 'Override RPC endpoint')
     .option('--verbose', 'Verbose output')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solana-compass/cli",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Solana CLI for Humans and LLM Agents",
   "type": "module",
   "bin": {
@@ -34,7 +34,9 @@
   },
   "files": [
     "bin/",
-    "dist/"
+    "dist/",
+    "skills/",
+    ".claude-plugin/"
   ],
   "repository": {
     "type": "git",

package/skills/solana-payments-wallets-trading/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: solana-payments-wallets-trading
+description: >-
+  Pay people in SOL or USDC, buy and sell tokens, check prices, manage Solana
+  wallets, stake SOL, earn yield through lending, and track portfolio
+  performance — all from the command line. No API keys, no private key env
+  vars. Use when the user wants to send crypto, trade, check balances, earn
+  yield, or see how their holdings are doing.
+license: MIT
+metadata:
+  author: solanaguide
+  version: 0.2.0
+  openclaw:
+    requires:
+      bins:
+        - node
+        - npx
+---
+
+# Payments, Wallets and Trading on Solana
+
+Sol is a command-line tool that lets you work with Solana the way you'd
+describe it out loud. Instead of constructing transactions and managing
+program instructions, you say what you want: pay someone, buy a token,
+stake your SOL.
+
+Keys live locally on disk — no private keys in environment variables,
+no API keys to configure.
+
+## Get Set Up
+
+```bash
+npm install -g @solana-compass/cli
+sol config set rpc.url https://your-rpc-endpoint.com
+sol wallet create --name my-wallet
+```
+
+The public RPC endpoint rate-limits aggressively. Use a dedicated RPC
+for anything beyond testing — Helius, Triton, and QuickNode all offer
+free tiers.
+
+Or run without installing:
+
+```bash
+npx @solana-compass/cli wallet list
+```
+
+Requires Node.js >= 20.
+
+## Pay Someone
+
+Send SOL, USDC, or any Solana token to a wallet address.
+
+```bash
+sol token send 50 usdc GkX...abc
+sol token send 2 sol 7nY...xyz
+sol token send 1000 bonk AgE...def --yes
+```
+
+Use `--yes` to skip the confirmation prompt — useful for automated
+payments between agents or apps. Confirmations are also skipped
+automatically in `--json` mode.
+
+See references/trading-commands.md for the full send reference.
+
+## Buy and Sell Tokens
+
+Swap any token for any other token. Prices come from Jupiter — best
+rate across every Solana DEX, no API key needed.
+
+```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 50 usdc bonk --quote-only  # preview without executing
+```
+
+Every swap records the price at execution time, so you can track
+cost basis and P&L later.
+
+See references/trading-commands.md for slippage, wallet selection, etc.
+
+## Check Prices
+
+```bash
+sol token price sol
+sol token price sol usdc bonk eth       # multiple at once
+```
+
+## See What You Have
+
+```bash
+sol wallet balance                      # all tokens with USD values
+sol token list                          # just token balances
+sol wallet list                         # all your wallets
+```
+
+## Create and Manage Wallets
+
+Wallets are local key files in `~/.sol/wallets/` — no seed phrases
+in environment variables.
+
+```bash
+sol wallet create                       # new wallet, auto-named
+sol wallet create --name trading        # pick a name
+sol wallet import --solana-cli          # import from Solana CLI
+sol wallet set-default trading          # switch active wallet
+```
+
+Any command can target a specific wallet with `--wallet <name>`.
+
+See references/wallet-commands.md for import, export, labels, history.
+
+## Stake SOL
+
+Delegate SOL to a validator and earn staking rewards. One command
+handles the entire process — creating the stake account, funding it,
+and delegating.
+
+```bash
+sol stake new 10                        # stake 10 SOL
+sol stake list                          # your stake accounts + claimable tips
+sol stake claim-mev                     # compound MEV rewards
+sol stake withdraw 7gK...abc            # unstake
+```
+
+See references/staking-commands.md for validator selection, partial
+withdrawals, and force unstake.
+
+## Earn Yield by Lending
+
+Deposit tokens into Kamino Finance to earn interest, or borrow
+against your deposits.
+
+```bash
+sol lend rates usdc                     # current APY
+sol lend deposit 100 usdc               # start earning
+sol lend borrow 500 usdc --collateral sol
+sol lend positions                      # everything you've got open
+```
+
+See references/lending-commands.md for full details.
+
+## Track How Your Portfolio Is Doing
+
+See everything in one place — tokens, staked SOL, lending positions.
+
+```bash
+sol portfolio                           # the full picture
+sol portfolio snapshot --label "monday"
+sol portfolio compare                   # what changed since last snapshot
+sol portfolio pnl                       # profit and loss over time
+```
+
+See references/portfolio-commands.md for snapshot management.
+
+## Structured Output
+
+Every command supports `--json` for structured output. In JSON mode,
+confirmations are skipped automatically.
+
+```json
+{ "ok": true, "data": { ... }, "meta": { "elapsed_ms": 450 } }
+```
+
+Error codes are `UPPER_SNAKE_CASE` (e.g. `SWAP_FAILED`). Check the
+`ok` field before reading `data`.
+
+See references/json-output-format.md for the full schema.
+
+## Other Useful Commands
+
+```bash
+sol network                             # epoch, TPS, staking APY
+sol tx 4xK9...abc                       # look up any transaction
+sol config set rpc.url <url>            # change RPC endpoint
+```
+
+## Tips
+
+- Use mint addresses instead of symbols when you know the exact token
+  (avoids symbol ambiguity)
+- Use `--quote-only` on swaps to preview before committing
+- Use `--wallet <name>` to target a specific wallet
+- The transaction log tracks all operations with USD prices at
+  execution time — useful for cost basis and P&L
+
+## Troubleshooting
+
+See references/troubleshooting.md for common issues (RPC rate limits,
+token resolution, transaction timeouts).

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}`);
+}
+```