jaspervault_cli 1.1.0 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/README.md +8 -19
  2. package/dist/bin/jv.js +4 -2
  3. package/dist/bin/jv.js.map +1 -1
  4. package/dist/src/commands/deposit.js +1 -1
  5. package/dist/src/commands/deposit.js.map +1 -1
  6. package/dist/src/commands/install.js +1 -1
  7. package/dist/src/commands/install.js.map +1 -1
  8. package/dist/src/commands/order.js +5 -5
  9. package/dist/src/commands/order.js.map +1 -1
  10. package/dist/src/commands/orders.js +2 -2
  11. package/dist/src/commands/orders.js.map +1 -1
  12. package/dist/src/commands/sl.js +3 -3
  13. package/dist/src/commands/sl.js.map +1 -1
  14. package/dist/src/commands/tp.js +3 -3
  15. package/dist/src/commands/tp.js.map +1 -1
  16. package/dist/src/commands/vault.d.ts +1 -6
  17. package/dist/src/commands/vault.js +15 -70
  18. package/dist/src/commands/vault.js.map +1 -1
  19. package/dist/src/commands/wallet.d.ts +2 -0
  20. package/dist/src/commands/wallet.js +126 -0
  21. package/dist/src/commands/wallet.js.map +1 -0
  22. package/dist/src/commands/withdraw.js +2 -2
  23. package/dist/src/commands/withdraw.js.map +1 -1
  24. package/dist/src/mcp/index.js +3 -7
  25. package/dist/src/mcp/index.js.map +1 -1
  26. package/dist/src/mcp/tools.js +1 -1
  27. package/dist/src/mcp/tools.js.map +1 -1
  28. package/dist/src/services/key-manager.js +4 -12
  29. package/dist/src/services/key-manager.js.map +1 -1
  30. package/dist/src/services/order-signer.js +2 -2
  31. package/dist/src/services/order-signer.js.map +1 -1
  32. package/dist/src/services/profile-manager.d.ts +49 -0
  33. package/dist/src/services/profile-manager.js +179 -0
  34. package/dist/src/services/profile-manager.js.map +1 -0
  35. package/dist/src/services/vault-profile.js +4 -12
  36. package/dist/src/services/vault-profile.js.map +1 -1
  37. package/dist/src/templates/skill-content/SKILL.core.md +10 -1
  38. package/dist/src/templates/skill-content/references/onboarding.md +1 -1
  39. package/dist/src/templates/skill-content/references/queries.md +20 -0
  40. package/docs/OPENCLAW_GUIDE.md +136 -0
  41. package/docs/USER_GUIDE.md +262 -0
  42. package/package.json +3 -2
@@ -1 +1 @@
1
- {"version":3,"file":"vault-profile.js","sourceRoot":"","sources":["../../../src/services/vault-profile.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,IAAI,CAAC;AACnF,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAG5B,SAAS,QAAQ;IACf,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,EAAE,EAAE,cAAc,CAAC,CAAC;AACjF,CAAC;AAED,SAAS,cAAc;IACrB,OAAO,IAAI,CAAC,QAAQ,EAAE,EAAE,cAAc,CAAC,CAAC;AAC1C,CAAC;AAED,SAAS,SAAS;IAChB,MAAM,GAAG,GAAG,QAAQ,EAAE,CAAC;IACvB,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACrB,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtC,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAgB;IAC/C,IAAI,CAAC,UAAU,CAAC,cAAc,EAAE,CAAC,EAAE,CAAC;QAClC,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,GAAG,GAAG,YAAY,CAAC,cAAc,EAAE,EAAE,OAAO,CAAC,CAAC;IACpD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAiB,CAAC;IAChD,IAAI,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,iBAAiB,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QACnE,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,OAAO,IAAI,OAAO,CAAC,OAAO,KAAK,OAAO,EAAE,CAAC;QAC3C,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAqB;IACpD,SAAS,EAAE,CAAC;IACZ,MAAM,IAAI,GAAG,cAAc,EAAE,CAAC;IAC9B,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACvE,IAAI,CAAC;QACH,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,gDAAgD;IAClD,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,6BAA6B,CAAC,OAAqB,EAAE,IAAsB;IACzF,MAAM,UAAU,GAAG,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7C,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAa,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC;IAC7E,OAAO,KAAK,EAAE,OAAO,IAAI,IAAI,CAAC;AAChC,CAAC"}
1
+ {"version":3,"file":"vault-profile.js","sourceRoot":"","sources":["../../../src/services/vault-profile.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,IAAI,CAAC;AACxE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAEvF,SAAS,cAAc;IACrB,OAAO,IAAI,CAAC,uBAAuB,EAAE,EAAE,cAAc,CAAC,CAAC;AACzD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAgB;IAC/C,IAAI,CAAC,UAAU,CAAC,cAAc,EAAE,CAAC,EAAE,CAAC;QAClC,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,GAAG,GAAG,YAAY,CAAC,cAAc,EAAE,EAAE,OAAO,CAAC,CAAC;IACpD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAiB,CAAC;IAChD,IAAI,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,iBAAiB,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QACnE,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,OAAO,IAAI,OAAO,CAAC,OAAO,KAAK,OAAO,EAAE,CAAC;QAC3C,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAqB;IACpD,sBAAsB,EAAE,CAAC;IACzB,MAAM,IAAI,GAAG,cAAc,EAAE,CAAC;IAC9B,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACvE,IAAI,CAAC;QACH,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,gDAAgD;IAClD,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,6BAA6B,CAAC,OAAqB,EAAE,IAAsB;IACzF,MAAM,UAAU,GAAG,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7C,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAa,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC;IAC7E,OAAO,KAAK,EAAE,OAAO,IAAI,IAAI,CAAC;AAChC,CAAC"}
@@ -50,6 +50,7 @@ When the user wants to trade, first check if their vault is ready:
50
50
  | Check job status | `get_job_status` | `job_id` | [queries](references/queries.md) |
51
51
  | List limit orders | `list_limit_orders` | `wallet` | [queries](references/queries.md) |
52
52
  | Cancel limit order | `cancel_limit_order` | `limit_order_id` | [queries](references/queries.md) |
53
+ | Check for CLI update | `check_update` | — | [queries](references/queries.md) |
53
54
 
54
55
  ## Key Behaviors
55
56
 
@@ -109,8 +110,16 @@ Call `list_orders` to confirm the position is closed or reduced.
109
110
  | "Let me check if jv is installed" | IRRELEVANT. MCP server runs CLI internally. |
110
111
  | "I'll close the position without checking current margin" | WRONG. Always call `list_orders` first to get the exact side and margin before closing. |
111
112
 
113
+ ## Update Notices
114
+
115
+ MCP tool responses may include an update notice when a newer CLI version is available. When you see this notice, inform the user:
116
+ - Tell them a new version is available (include version numbers)
117
+ - Ask them to run `jv update` to upgrade
118
+
119
+ You can also proactively call `check_update` to verify the CLI is up to date.
120
+
112
121
  ## Security
113
122
 
114
123
  - Never log or display private keys, signatures, or API keys.
115
124
  - Delegation wallet is stored in `~/.jaspervault/keys.json` — never read or display this file.
116
- - Never ask the user to set `PRIVATE_KEY` — that's for CI/automation only.
125
+ - Never ask the user for private keys.
@@ -54,7 +54,7 @@ The tool automatically:
54
54
  |---------|---------------|
55
55
  | Asking user for private key after setup | Delegation key is auto-generated. User never provides keys. |
56
56
  | Saying "profile.json is empty" | `wallet_setup` saves profile automatically on success. |
57
- | Suggesting `vault init` | That's for CI/automation with PRIVATE_KEY env var. Never suggest it. |
57
+ | Suggesting private key setup | There is no private key mode. `wallet_setup` is the only way. |
58
58
  | Saying "CLI needs separate initialization" | `wallet_setup` IS the initialization. One step, fully done. |
59
59
  | Running `jv orders list` in terminal | Use `list_orders` MCP tool instead. |
60
60
 
@@ -162,6 +162,26 @@ Check execution status of an async job (market order, option creation, etc.).
162
162
 
163
163
  ---
164
164
 
165
+ ## 7. Check for Updates — `check_update`
166
+
167
+ No parameters required. Checks if a newer version of jaspervault_cli is available.
168
+
169
+ ### Response
170
+
171
+ ```json
172
+ {
173
+ "updateAvailable": true,
174
+ "currentVersion": "1.0.32",
175
+ "latestVersion": "1.0.35"
176
+ }
177
+ ```
178
+
179
+ When `updateAvailable` is `true`, tell the user to run `jv update` to upgrade.
180
+
181
+ **Note:** Any MCP tool response may also include an update notice as a second text block when an update is available. When you see this, relay it to the user.
182
+
183
+ ---
184
+
165
185
  ## Error Handling
166
186
 
167
187
  When a tool fails, check the error message:
@@ -0,0 +1,136 @@
1
+ # OpenClaw Setup Guide
2
+
3
+ Trade perpetual contracts with built-in hedge protection on JasperVault through OpenClaw. Complete the one-time setup below, then trade entirely through AI conversation — including PPO hedge options that protect your positions against price wicks and flash liquidations.
4
+
5
+ ## Prerequisites
6
+
7
+ | Requirement | How to verify |
8
+ |-------------|--------------|
9
+ | Node.js 18+ | `node --version` — install from [nodejs.org](https://nodejs.org) if needed |
10
+ | OpenClaw | Installed and running |
11
+ | Browser wallet | MetaMask, Rabby, or similar — for one-time delegation signing |
12
+
13
+ ## Setup (One-Time)
14
+
15
+ ### Step 1: Install the CLI
16
+
17
+ ```bash
18
+ npm install -g jaspervault_cli
19
+ jv --version # verify installation
20
+ ```
21
+
22
+ ### Step 2: Install the JasperVault Skill
23
+
24
+ ```bash
25
+ jv install --ai openclaw
26
+ ```
27
+
28
+ This installs the trading skill to `~/.openclaw/skills/jasper-vault-cli/SKILL.md`. OpenClaw will automatically detect it on next launch.
29
+
30
+ > To update an existing installation: `jv install --ai openclaw --force`
31
+
32
+ ### Step 3: Initialize Your Wallet
33
+
34
+ Open OpenClaw and say:
35
+
36
+ > "I want to start trading"
37
+
38
+ OpenClaw will:
39
+ 1. Call `wallet_setup` and provide a URL
40
+ 2. Open the link in your browser, connect your wallet, and sign the delegation authorization
41
+ 3. Wait while OpenClaw confirms the setup (up to 2 minutes)
42
+
43
+ That's it. Your wallet is now initialized and all trading tools are ready.
44
+
45
+ **Alternative — manual setup via terminal:**
46
+
47
+ ```bash
48
+ jv enable --pretty
49
+ ```
50
+
51
+ ### Step 4: Deposit (Optional)
52
+
53
+ Tell OpenClaw:
54
+
55
+ > "Deposit 100 USDC"
56
+
57
+ A browser page opens for you to approve the cross-chain transfer from Base to JasperVault. Funds typically arrive within a few minutes.
58
+
59
+ ## Trading
60
+
61
+ Once setup is complete, talk to OpenClaw in natural language:
62
+
63
+ | What you say | What happens |
64
+ |-------------|-------------|
65
+ | "Long BTC with 100 USDC and PPO" | Opens a protected long position |
66
+ | "Long BTC with 100 USDC, 50x" | Opens a leveraged long position |
67
+ | "Short BTC with 50 USDC at 95000" | Places a limit short order |
68
+ | "Add PPO protection to order 42" | Adds hedge option to existing position |
69
+ | "Protect order 42 with OTM tier 3, 8h" | Custom PPO: OTM strike offset, 8-hour expiry |
70
+ | "Close my BTC position" | Queries position, then closes it |
71
+ | "Set TP at 110000 for order 99" | Creates a take-profit limit order |
72
+ | "Set SL at 88000 for order 99" | Creates a stop-loss limit order |
73
+ | "Show my positions" | Lists all active positions |
74
+ | "What's the BTC price?" | Fetches real-time market price |
75
+ | "Withdraw 100 USDC" | Opens browser to sign withdrawal |
76
+
77
+ OpenClaw translates your intent into the appropriate tool calls and returns results in natural language.
78
+
79
+ ### PPO Hedge Protection
80
+
81
+ PPO (Perpetual Protection Option) is an on-chain hedge option unique to JasperVault. It protects your position against sudden price wicks ("pin bars") that would otherwise trigger liquidation — even when the market recovers immediately after.
82
+
83
+ Unlike stop-loss orders that execute at the wick price and lock in losses, PPO uses a peer-to-peer fully collateralized option contract. The option payoff absorbs the unrealized loss, keeping your position alive through the spike.
84
+
85
+ **How to use PPO:**
86
+
87
+ | What you say | What happens |
88
+ |-------------|-------------|
89
+ | "Open long BTC with PPO" | Opens position + ATM hedge, 30-min expiry |
90
+ | "Add protection to order 42" | Adds PPO to existing position |
91
+ | "Protect with OTM tier 3 for 8 hours" | Custom: OTM strike (0.3% offset), 8h expiry |
92
+
93
+ **Options:**
94
+ - **Category:** ATM (strike = current price) or OTM (offset 0.1%–0.5% via tiers 1–5)
95
+ - **Expiry:** 30 minutes (default) or 8 hours
96
+ - **Hedge type:** Automatic — PUT for longs, CALL for shorts
97
+
98
+ ## Environment Variables (Optional)
99
+
100
+ The CLI works with default settings. Only configure these if needed:
101
+
102
+ ```bash
103
+ # Custom API endpoint (e.g., for local development)
104
+ export JV_API_URL=https://your-endpoint.example.com
105
+
106
+ # API authentication (if required by your deployment)
107
+ export JV_API_KEY=your-token
108
+ ```
109
+
110
+ Add to `~/.zshrc` or `~/.bashrc` for persistence, then `source ~/.zshrc`.
111
+
112
+ > **Note:** Browser signing mode does not require `PRIVATE_KEY`. Your keys stay in your browser wallet at all times.
113
+
114
+ ## Troubleshooting
115
+
116
+ **Wallet page doesn't open or wallet prompt doesn't appear**
117
+ - Ensure your browser wallet extension is installed and unlocked
118
+ - Some wallets require clicking the extension icon to see pending signature requests
119
+
120
+ **"Delegation key not found" error**
121
+ - Run `jv enable --pretty` to re-initialize
122
+ - Verify `~/.jaspervault/keys.json` exists: `ls ~/.jaspervault/`
123
+
124
+ **OpenClaw doesn't recognize trading commands**
125
+ - Verify the skill is installed: `ls ~/.openclaw/skills/jasper-vault-cli/`
126
+ - Reinstall if needed: `jv install --ai openclaw --force`
127
+ - Restart OpenClaw after installation
128
+
129
+ **Deposit shows "not arrived" after completion**
130
+ - Cross-chain bridging via Hyperlane takes 1–3 minutes. Wait and retry.
131
+
132
+ ## Further Reading
133
+
134
+ - [User Guide](USER_GUIDE.md) — Complete CLI reference and configuration
135
+ - [JasperVault](https://www.jaspervault.io/) — Protocol documentation
136
+ - CLI help: `jv --help`, `jv order --help`, `jv enable --help`
@@ -0,0 +1,262 @@
1
+ # User Guide
2
+
3
+ Complete reference for the JasperVault CLI (`jv`). This guide covers installation, wallet setup, trading operations, and advanced configuration.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ npm install -g jaspervault_cli
9
+ ```
10
+
11
+ Verify:
12
+
13
+ ```bash
14
+ jv --version
15
+ ```
16
+
17
+ **Requirements:** Node.js 18+
18
+
19
+ ## Wallet Setup
20
+
21
+ Before trading, you need to initialize your vault. This creates an AA (Account Abstraction) wallet and a local delegation key.
22
+
23
+ ```bash
24
+ jv enable --pretty
25
+ ```
26
+
27
+ 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.
28
+
29
+ After setup completes, your delegation key and vault profile are saved to `~/.jaspervault/`. All subsequent commands use these automatically.
30
+
31
+ ## Deposits & Withdrawals
32
+
33
+ Bridge assets between Base and JasperVault via Hyperlane.
34
+
35
+ **Deposit:**
36
+
37
+ ```bash
38
+ jv deposit --token usdc --amount 100 --pretty
39
+ ```
40
+
41
+ **Withdraw:**
42
+
43
+ ```bash
44
+ jv withdraw --token usdc --amount 100 --pretty
45
+ ```
46
+
47
+ Both commands open a hosted web page for you to approve the transaction in your browser wallet.
48
+
49
+ ## Trading
50
+
51
+ ### Market Orders
52
+
53
+ Execute immediately at current market price.
54
+
55
+ ```bash
56
+ # Long BTC, 100 USDC margin, 50x leverage
57
+ jv order create --side long --symbol JBTC --margin 100 --leverage 50
58
+
59
+ # Short BTC, 50 USDC margin, 100x leverage
60
+ jv order create --side short --symbol JBTC --margin 50 --leverage 100
61
+ ```
62
+
63
+ Market orders return a `jobId`. The order typically confirms on-chain within seconds.
64
+
65
+ ### Limit Orders
66
+
67
+ Execute when price reaches the target.
68
+
69
+ ```bash
70
+ # Short BTC at $95,000
71
+ jv order create --side short --symbol JBTC --margin 50 --leverage 100 --limit-price 95000
72
+ ```
73
+
74
+ Limit orders return a `limitOrderId` and remain active until triggered, expired, or cancelled.
75
+
76
+ ### Close a Position
77
+
78
+ To close, create an order with the **opposite side** and the **same margin** as your existing position.
79
+
80
+ ```bash
81
+ # Full close: if your position is LONG with 100 USDC margin
82
+ jv order create --side short --symbol JBTC --margin 100
83
+
84
+ # Partial close: reduce by half
85
+ jv order create --side short --symbol JBTC --margin 50
86
+ ```
87
+
88
+ Always check your current position first with `jv orders list --pretty` to confirm the exact side and margin.
89
+
90
+ ### Take-Profit & Stop-Loss
91
+
92
+ ```bash
93
+ jv tp set --order-id 99 --price 105000 --symbol JBTC
94
+ jv sl set --order-id 99 --price 88000 --symbol JBTC
95
+ ```
96
+
97
+ ## PPO Hedge Protection
98
+
99
+ PPO (Perpetual Protection Option) is JasperVault's on-chain hedge option that protects leveraged positions against sudden price wicks and liquidation cascades.
100
+
101
+ ### Why PPO
102
+
103
+ 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:
104
+
105
+ - **Survives the wick** — the option payoff offsets unrealized loss, keeping your position alive through the spike
106
+ - **No slippage** — peer-to-peer fully collateralized settlement on-chain, independent of orderbook depth or liquidity
107
+ - **Auto hedge type** — LONG positions get PUT options, SHORT positions get CALL options (selected automatically)
108
+
109
+ ### Using PPO
110
+
111
+ **Open a position with PPO:**
112
+
113
+ ```bash
114
+ jv order create --side long --symbol JBTC --margin 100 --leverage 50 --ppo
115
+ ```
116
+
117
+ **Add PPO to an existing position:**
118
+
119
+ ```bash
120
+ jv order protect --order-id 42 --symbol JBTC
121
+ ```
122
+
123
+ **Customize PPO parameters:**
124
+
125
+ ```bash
126
+ jv order create --side long --symbol JBTC --margin 100 --leverage 50 \
127
+ --ppo --ppo-expire 8h --ppo-category OTM --ppo-tier 3
128
+ ```
129
+
130
+ ### PPO Parameters
131
+
132
+ | Parameter | Options | Default | Description |
133
+ |-----------|---------|---------|-------------|
134
+ | `--ppo` | flag | off | Enable PPO protection |
135
+ | `--ppo-category` | `ATM`, `OTM` | `ATM` | ATM = strike at current price; OTM = offset from current price |
136
+ | `--ppo-tier` | `1`–`5` | — | OTM strike offset (0.1%–0.5%). Required when category is OTM |
137
+ | `--ppo-expire` | `30m`, `8h` | `30m` | Option expiry duration |
138
+
139
+ ### OTM Tiers
140
+
141
+ | Tier | Strike Offset | Use Case |
142
+ |------|---------------|----------|
143
+ | 1 | 0.1% | Tight protection, higher premium |
144
+ | 2 | 0.2% | Balanced |
145
+ | 3 | 0.3% | Moderate offset |
146
+ | 4 | 0.4% | Wider offset, lower premium |
147
+ | 5 | 0.5% | Maximum offset, lowest premium |
148
+
149
+ ### PPO Lifecycle
150
+
151
+ - **Combine with any operation** — PPO can be added when opening, adding size, or setting TP/SL
152
+ - **Auto-cancellation** — Executing any position operation *without* `--ppo` automatically cancels the existing PPO on that position
153
+ - **Keep PPO on reduce** — Add `--ppo` when partially closing to maintain protection on the remaining position
154
+ - **No separate cancel** — There is no "cancel PPO" command. To remove PPO, execute any position operation without the `--ppo` flag
155
+
156
+ ## Querying Data
157
+
158
+ ```bash
159
+ # List active positions
160
+ jv orders list --pretty
161
+
162
+ # Get specific order details
163
+ jv orders get <orderId> --pretty
164
+
165
+ # Portfolio statistics
166
+ jv orders stats --pretty
167
+
168
+ # Real-time price
169
+ jv price --symbol JBTC --pretty
170
+
171
+ # Check market order execution status
172
+ jv job status <jobId> --pretty
173
+ ```
174
+
175
+ ### Limit Order Management
176
+
177
+ ```bash
178
+ # List limit orders
179
+ jv limit-order list --wallet 0x... --status PENDING --pretty
180
+
181
+ # Check status
182
+ jv limit-order status <limitOrderId>
183
+
184
+ # Cancel
185
+ jv limit-order cancel <limitOrderId>
186
+ ```
187
+
188
+ ## AI Platform Integration
189
+
190
+ Install JasperVault trading capabilities into your AI agent:
191
+
192
+ ```bash
193
+ jv install --ai claude # Claude Code (project-level)
194
+ jv install --ai claude --global # Claude Code (user-level)
195
+ jv install --ai cursor # Cursor (project-level)
196
+ jv install --ai cursor --global # Cursor (user-level)
197
+ jv install --ai openclaw # OpenClaw
198
+ jv install # All platforms (global)
199
+ ```
200
+
201
+ After installation, your AI can execute trades via MCP tools or skills. See the [OpenClaw Guide](OPENCLAW_GUIDE.md) for platform-specific setup details.
202
+
203
+ ## Configuration
204
+
205
+ All environment variables are optional. The CLI works out of the box with sensible defaults.
206
+
207
+ | Variable | Description | Default |
208
+ |----------|-------------|---------|
209
+ | `JV_API_URL` | Trading API endpoint | Production endpoint |
210
+ | `JV_API_KEY` | Bearer token for API auth | — |
211
+ | `JV_TIMEOUT` | Request timeout (ms) | 30000 |
212
+ | `JV_DELEGATION_KEY` | Delegation wallet key | Auto-generated |
213
+ | `JV_BASE_RPC_URL` | Base chain RPC | Built-in |
214
+ | `JV_JASPERVAULT_RPC_URL` | JasperVault chain RPC | Built-in |
215
+ | `JV_SUBGRAPH_URL` | Subgraph endpoint | Built-in |
216
+
217
+ ### Local Override Example
218
+
219
+ ```bash
220
+ export JV_API_URL=http://localhost:3000
221
+ ```
222
+
223
+ ### Configuration Files
224
+
225
+ | Path | Purpose |
226
+ |------|---------|
227
+ | `~/.jaspervault/keys.json` | Delegation wallet key (auto-generated) |
228
+ | `~/.jaspervault/profile.json` | Vault addresses and type mappings |
229
+
230
+ ## Output Formats
231
+
232
+ - **JSON** (default) — Machine-readable, suitable for scripting and piping
233
+ - **Pretty** — Human-readable tables. Append `--pretty` to any command
234
+
235
+ ## Exit Codes
236
+
237
+ | Code | Meaning |
238
+ |------|---------|
239
+ | 0 | Success |
240
+ | 1 | Configuration error (missing params, invalid input) |
241
+ | 2 | Network / HTTP error |
242
+ | 3 | Business error (API-level rejection) |
243
+
244
+ ## Updates
245
+
246
+ ```bash
247
+ jv update # Check and install latest version
248
+ ```
249
+
250
+ ## FAQ
251
+
252
+ **Q: Do I need to export my private key?**
253
+ No. Browser signing keeps your keys in your wallet. Your private key never leaves the browser.
254
+
255
+ **Q: How do I switch networks?**
256
+ Set `JV_API_URL` to your target environment's API endpoint.
257
+
258
+ **Q: Is my delegation key safe?**
259
+ 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.
260
+
261
+ **Q: What trading pairs are available?**
262
+ Currently BTC perpetuals (symbol: `JBTC`). Additional pairs will be added — check `jv price --symbol <symbol>` for availability.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "jaspervault_cli",
3
- "version": "1.1.0",
3
+ "version": "1.1.1",
4
4
  "description": "JasperVault CLI for interacting with the JasperVault Manager API",
5
5
  "type": "module",
6
6
  "bin": {
@@ -19,7 +19,8 @@
19
19
  },
20
20
  "files": [
21
21
  "dist",
22
- "config"
22
+ "config",
23
+ "docs"
23
24
  ],
24
25
  "keywords": [
25
26
  "jaspervault",