jaspervault_cli 1.0.33 → 1.1.1

package/docs/USER_GUIDE.md

@@ -0,0 +1,262 @@
+# User Guide
+
+Complete reference for the JasperVault CLI (`jv`). This guide covers installation, wallet setup, trading operations, and advanced configuration.
+
+## Installation
+
+```bash
+npm install -g jaspervault_cli
+```
+
+Verify:
+
+```bash
+jv --version
+```
+
+**Requirements:** Node.js 18+
+
+## Wallet Setup
+
+Before trading, you need to initialize your vault. This creates an AA (Account Abstraction) wallet and a local delegation key.
+
+```bash
+jv enable --pretty
+```
+
+This opens a hosted web page where you connect your wallet (MetaMask, Rabby, etc.) and sign a delegation authorization. Your private key never leaves the browser.
+
+After setup completes, your delegation key and vault profile are saved to `~/.jaspervault/`. All subsequent commands use these automatically.
+
+## Deposits & Withdrawals
+
+Bridge assets between Base and JasperVault via Hyperlane.
+
+**Deposit:**
+
+```bash
+jv deposit --token usdc --amount 100 --pretty
+```
+
+**Withdraw:**
+
+```bash
+jv withdraw --token usdc --amount 100 --pretty
+```
+
+Both commands open a hosted web page for you to approve the transaction in your browser wallet.
+
+## Trading
+
+### Market Orders
+
+Execute immediately at current market price.
+
+```bash
+# Long BTC, 100 USDC margin, 50x leverage
+jv order create --side long --symbol JBTC --margin 100 --leverage 50
+
+# Short BTC, 50 USDC margin, 100x leverage
+jv order create --side short --symbol JBTC --margin 50 --leverage 100
+```
+
+Market orders return a `jobId`. The order typically confirms on-chain within seconds.
+
+### Limit Orders
+
+Execute when price reaches the target.
+
+```bash
+# Short BTC at $95,000
+jv order create --side short --symbol JBTC --margin 50 --leverage 100 --limit-price 95000
+```
+
+Limit orders return a `limitOrderId` and remain active until triggered, expired, or cancelled.
+
+### Close a Position
+
+To close, create an order with the **opposite side** and the **same margin** as your existing position.
+
+```bash
+# Full close: if your position is LONG with 100 USDC margin
+jv order create --side short --symbol JBTC --margin 100
+
+# Partial close: reduce by half
+jv order create --side short --symbol JBTC --margin 50
+```
+
+Always check your current position first with `jv orders list --pretty` to confirm the exact side and margin.
+
+### Take-Profit & Stop-Loss
+
+```bash
+jv tp set --order-id 99 --price 105000 --symbol JBTC
+jv sl set --order-id 99 --price 88000 --symbol JBTC
+```
+
+## PPO Hedge Protection
+
+PPO (Perpetual Protection Option) is JasperVault's on-chain hedge option that protects leveraged positions against sudden price wicks and liquidation cascades.
+
+### Why PPO
+
+In leveraged perpetual trading, flash crashes and price wicks ("pin bars") can liquidate positions in seconds — even when the market quickly recovers. Traditional stop-loss orders execute *at* the wick price, locking in maximum loss. PPO solves this by attaching a real option contract to your position:
+
+- **Survives the wick** — the option payoff offsets unrealized loss, keeping your position alive through the spike
+- **No slippage** — peer-to-peer fully collateralized settlement on-chain, independent of orderbook depth or liquidity
+- **Auto hedge type** — LONG positions get PUT options, SHORT positions get CALL options (selected automatically)
+
+### Using PPO
+
+**Open a position with PPO:**
+
+```bash
+jv order create --side long --symbol JBTC --margin 100 --leverage 50 --ppo
+```
+
+**Add PPO to an existing position:**
+
+```bash
+jv order protect --order-id 42 --symbol JBTC
+```
+
+**Customize PPO parameters:**
+
+```bash
+jv order create --side long --symbol JBTC --margin 100 --leverage 50 \
+  --ppo --ppo-expire 8h --ppo-category OTM --ppo-tier 3
+```
+
+### PPO Parameters
+
+| Parameter | Options | Default | Description |
+|-----------|---------|---------|-------------|
+| `--ppo` | flag | off | Enable PPO protection |
+| `--ppo-category` | `ATM`, `OTM` | `ATM` | ATM = strike at current price; OTM = offset from current price |
+| `--ppo-tier` | `1`–`5` | — | OTM strike offset (0.1%–0.5%). Required when category is OTM |
+| `--ppo-expire` | `30m`, `8h` | `30m` | Option expiry duration |
+
+### OTM Tiers
+
+| Tier | Strike Offset | Use Case |
+|------|---------------|----------|
+| 1 | 0.1% | Tight protection, higher premium |
+| 2 | 0.2% | Balanced |
+| 3 | 0.3% | Moderate offset |
+| 4 | 0.4% | Wider offset, lower premium |
+| 5 | 0.5% | Maximum offset, lowest premium |
+
+### PPO Lifecycle
+
+- **Combine with any operation** — PPO can be added when opening, adding size, or setting TP/SL
+- **Auto-cancellation** — Executing any position operation *without* `--ppo` automatically cancels the existing PPO on that position
+- **Keep PPO on reduce** — Add `--ppo` when partially closing to maintain protection on the remaining position
+- **No separate cancel** — There is no "cancel PPO" command. To remove PPO, execute any position operation without the `--ppo` flag
+
+## Querying Data
+
+```bash
+# List active positions
+jv orders list --pretty
+
+# Get specific order details
+jv orders get <orderId> --pretty
+
+# Portfolio statistics
+jv orders stats --pretty
+
+# Real-time price
+jv price --symbol JBTC --pretty
+
+# Check market order execution status
+jv job status <jobId> --pretty
+```
+
+### Limit Order Management
+
+```bash
+# List limit orders
+jv limit-order list --wallet 0x... --status PENDING --pretty
+
+# Check status
+jv limit-order status <limitOrderId>
+
+# Cancel
+jv limit-order cancel <limitOrderId>
+```
+
+## AI Platform Integration
+
+Install JasperVault trading capabilities into your AI agent:
+
+```bash
+jv install --ai claude        # Claude Code (project-level)
+jv install --ai claude --global   # Claude Code (user-level)
+jv install --ai cursor        # Cursor (project-level)
+jv install --ai cursor --global   # Cursor (user-level)
+jv install --ai openclaw      # OpenClaw
+jv install                    # All platforms (global)
+```
+
+After installation, your AI can execute trades via MCP tools or skills. See the [OpenClaw Guide](OPENCLAW_GUIDE.md) for platform-specific setup details.
+
+## Configuration
+
+All environment variables are optional. The CLI works out of the box with sensible defaults.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `JV_API_URL` | Trading API endpoint | Production endpoint |
+| `JV_API_KEY` | Bearer token for API auth | — |
+| `JV_TIMEOUT` | Request timeout (ms) | 30000 |
+| `JV_DELEGATION_KEY` | Delegation wallet key | Auto-generated |
+| `JV_BASE_RPC_URL` | Base chain RPC | Built-in |
+| `JV_JASPERVAULT_RPC_URL` | JasperVault chain RPC | Built-in |
+| `JV_SUBGRAPH_URL` | Subgraph endpoint | Built-in |
+
+### Local Override Example
+
+```bash
+export JV_API_URL=http://localhost:3000
+```
+
+### Configuration Files
+
+| Path | Purpose |
+|------|---------|
+| `~/.jaspervault/keys.json` | Delegation wallet key (auto-generated) |
+| `~/.jaspervault/profile.json` | Vault addresses and type mappings |
+
+## Output Formats
+
+- **JSON** (default) — Machine-readable, suitable for scripting and piping
+- **Pretty** — Human-readable tables. Append `--pretty` to any command
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Configuration error (missing params, invalid input) |
+| 2 | Network / HTTP error |
+| 3 | Business error (API-level rejection) |
+
+## Updates
+
+```bash
+jv update          # Check and install latest version
+```
+
+## FAQ
+
+**Q: Do I need to export my private key?**
+No. Browser signing keeps your keys in your wallet. Your private key never leaves the browser.
+
+**Q: How do I switch networks?**
+Set `JV_API_URL` to your target environment's API endpoint.
+
+**Q: Is my delegation key safe?**
+The delegation key is generated locally and stored in `~/.jaspervault/keys.json`. It can only execute trades within the scope authorized by your delegation signature. It cannot transfer or withdraw funds without additional browser signing.
+
+**Q: What trading pairs are available?**
+Currently BTC perpetuals (symbol: `JBTC`). Additional pairs will be added — check `jv price --symbol <symbol>` for availability.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jaspervault_cli",
-  "version": "1.0.33",
+  "version": "1.1.1",
   "description": "JasperVault CLI for interacting with the JasperVault Manager API",
   "type": "module",
   "bin": {
@@ -19,7 +19,8 @@
   },
   "files": [
     "dist",
-    "config"
+    "config",
+    "docs"
   ],
   "keywords": [
     "jaspervault",