jaspervault_cli 1.0.28 → 1.0.30

package/dist/src/templates/skill-content/references/trading.md

@@ -1,245 +1,200 @@
 # Trading Reference
 
-## 1. Create Order (`jv order create`)
+> All tools below are MCP tools. Call them directly — never run `jv` shell commands.
 
-Open, close, reduce, or add size to perpetual positions.
-
-### Syntax
+## 1. Create Order — `create_order`
 
-```
-jv order create --side <long|short> --symbol <symbol> -m <margin> [options]
-```
+Open, close, reduce, or add size to perpetual positions.
 
-### Options
-
-| Option | Required | Default | Description |
-|--------|----------|---------|-------------|
-| `--side <long\|short>` | Yes | — | Position side |
-| `--symbol <symbol>` | Yes | — | Asset symbol (e.g., `JBTC`, `CBBTC`) |
-| `-m, --margin <usdc>` | Yes | — | Margin (collateral) in USDC |
-| `--leverage <n>` | No | `50` (from chain config) | Leverage multiplier |
-| `--limit-price <price>` | No | — | Limit price in USDC (omit for market order) |
-| `--margin-account <addr>` | No | from profile | Override margin vault address |
-| `--position-account <addr>` | No | from profile | Override position vault address |
-| `--ppo` | No | — | Enable PPO hedge option protection |
-| `--ppo-expire <duration>` | No | `30m` | PPO expiry: `30m` or `8h` |
-| `--ppo-category <ATM\|OTM>` | No | `ATM` | PPO option category |
-| `--ppo-tier <1-5>` | No | — | OTM strike offset tier (required if OTM) |
-| `--network <name>` | No | `jaspervault` | Network name |
-| `--ttl <seconds>` | No | `3600` | Order TTL in seconds |
-| `--pretty` | No | — | Pretty-print JSON output |
+### Parameters
+
+| Parameter | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `side` | Yes | — | `long` or `short` |
+| `symbol` | Yes | — | Asset symbol (e.g., `JBTC`, `CBBTC`) |
+| `margin` | Yes | — | Margin (collateral) in USDC |
+| `leverage` | No | `50` | Leverage multiplier |
+| `limit_price` | No | — | Limit price in USDC (omit for market order) |
+| `ppo` | No | — | `true` to enable PPO hedge option protection |
+| `ppo_expire` | No | `30m` | PPO expiry: `30m` or `8h` |
+| `ppo_category` | No | `ATM` | PPO option category: `ATM` or `OTM` |
+| `ppo_tier` | No | — | OTM strike offset tier 1-5 (required if OTM) |
+| `ttl` | No | `3600` | Order TTL in seconds |
 
 ### Market Order vs Limit Order
 
-- **Market order** (no `--limit-price`): Executes immediately at current market price. The CLI auto-waits up to 60s for the on-chain result via SSE.
-- **Limit order** (`--limit-price <N>`): Places a limit order that triggers when price reaches the target. Returns immediately with a `limitOrderId`.
+- **Market order** (no `limit_price`): Executes immediately. The tool auto-waits up to 60s for the on-chain result.
+- **Limit order** (`limit_price` set): Places a limit order that triggers when price reaches the target. Returns immediately with a `limitOrderId`.
 
-### Market Order Output (TWO JSON lines)
+### Market Order Response
 
-**Line 1 — Submission:**
-```json
-{"success":true,"orderType":"market","jobId":"MARKET_ORDER_xxx","statusUrl":"/api/job/status/...","streamUrl":"/api/job/stream/..."}
-```
+The tool returns the final execution result:
 
-**Line 2 — Execution result (auto-waits up to 60s):**
 ```json
-{"jobId":"MARKET_ORDER_xxx","status":"completed","transactionHash":"0x..."}
+{
+  "jobId": "MARKET_ORDER_xxx",
+  "status": "completed",
+  "transactionHash": "0x..."
+}
 ```
 
-**CRITICAL rules after market order execution:**
-1. If `status === "completed"` → the order IS executed. Do NOT retry or place another order.
+**After market order execution:**
+1. If `status === "completed"` → the order IS executed. Don't retry.
 2. If `status === "failed"` → report the error to the user.
-3. If `status === "timeout"` → use `jv job status <jobId> --pretty` to check later.
-4. The `operation` field (if present) contains raw on-chain data in wei — do NOT interpret it.
-5. To verify the actual position, run `jv orders list --pretty` and read the human-readable fields.
-6. Report: "Order executed. Tx: {transactionHash}. Let me check your updated position..." then run `jv orders list --pretty`.
+3. If `status === "timeout"` → use `get_job_status` with the `jobId` to check later.
+4. The `operation` field (if present) contains raw on-chain data in wei — don't interpret it.
+5. To verify the actual position, call `list_orders` and read the human-readable fields.
+6. Report: "Order executed. Tx: {transactionHash}. Let me check your updated position..." then call `list_orders`.
+
+### Limit Order Response
 
-**Limit order output:**
 ```json
-{"success":true,"orderType":"limit","limitOrderId":"0x..."}
+{
+  "success": true,
+  "orderType": "limit",
+  "limitOrderId": "0x..."
+}
 ```
-Tell the user: "Limit order placed. ID: {limitOrderId}."
 
-### Stderr Output
-
-Before submitting, the CLI prints an estimate to stderr:
-```
-Estimated: ~0.043860 JBTC @ $68,476 (~$3,000 JUSDC total, 50x)
-```
-This is informational only — the actual execution price may differ.
+Tell the user: "Limit order placed. ID: {limitOrderId}."
 
 ### Common Patterns
 
 **Open a long position (market):**
-```bash
-jv order create --side long --symbol JBTC -m 60 --pretty
+```json
+{ "side": "long", "symbol": "JBTC", "margin": 60 }
 ```
 
-**Open a short position (limit):**
-```bash
-jv order create --side short --symbol JBTC -m 100 --limit-price 72000 --pretty
+**Open a short position (limit at $72,000):**
+```json
+{ "side": "short", "symbol": "JBTC", "margin": 100, "limit_price": 72000 }
 ```
 
-**Close a long position (full close — use opposite side with same margin):**
-```bash
-jv order create --side short --symbol JBTC -m 60 --pretty
+**Close a long position (use opposite side with same margin):**
+```json
+{ "side": "short", "symbol": "JBTC", "margin": 60 }
 ```
 
 **Reduce a long position (partial close):**
-```bash
-jv order create --side short --symbol JBTC -m 30 --pretty
+```json
+{ "side": "short", "symbol": "JBTC", "margin": 30 }
 ```
 
 **Add size to existing long:**
-```bash
-jv order create --side long --symbol JBTC -m 50 --pretty
+```json
+{ "side": "long", "symbol": "JBTC", "margin": 50 }
 ```
 
 **Open with PPO protection (ATM, 30 min):**
-```bash
-jv order create --side long --symbol JBTC -m 60 --ppo --pretty
+```json
+{ "side": "long", "symbol": "JBTC", "margin": 60, "ppo": true }
 ```
 
 **Open with PPO protection (OTM tier 3, 8 hours):**
-```bash
-jv order create --side long --symbol JBTC -m 60 --ppo --ppo-expire 8h --ppo-category OTM --ppo-tier 3 --pretty
+```json
+{ "side": "long", "symbol": "JBTC", "margin": 60, "ppo": true, "ppo_expire": "8h", "ppo_category": "OTM", "ppo_tier": 3 }
 ```
 
 ---
 
-## 2. Add PPO Protection (`jv order protect`)
+## 2. Add PPO Protection — `protect_order`
 
 Add hedge option protection to an **existing position** without changing position size.
 
-### Syntax
-
-```
-jv order protect --order-id <id> --symbol <symbol> [options]
-```
-
-### Options
+### Parameters
 
-| Option | Required | Default | Description |
-|--------|----------|---------|-------------|
-| `--order-id <id>` | Yes | — | Existing perps order ID |
-| `--symbol <symbol>` | Yes | — | Asset symbol (e.g., `JBTC`) |
-| `--ppo-expire <duration>` | No | `30m` | Option expiry: `30m` or `8h` |
-| `--ppo-category <ATM\|OTM>` | No | `ATM` | Option category |
-| `--ppo-tier <1-5>` | No | — | OTM strike offset tier (required if OTM) |
-| `--network <name>` | No | `jaspervault` | Network name |
-| `--ttl <seconds>` | No | `3600` | Signature TTL in seconds |
-| `--pretty` | No | — | Pretty-print JSON output |
+| Parameter | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `order_id` | Yes | — | Existing perps order ID |
+| `symbol` | Yes | — | Asset symbol (e.g., `JBTC`) |
+| `ppo_expire` | No | `30m` | Option expiry: `30m` or `8h` |
+| `ppo_category` | No | `ATM` | Option category: `ATM` or `OTM` |
+| `ppo_tier` | No | — | OTM strike offset tier 1-5 (required if OTM) |
 
-### Output
+### Response
 
-The command auto-waits up to 60s for the on-chain result via SSE:
+The tool auto-waits up to 60s for the on-chain result:
 ```json
-{"jobId":"OPTION_ORDER_xxx","status":"completed","transactionHash":"0x..."}
+{
+  "jobId": "OPTION_ORDER_xxx",
+  "status": "completed",
+  "transactionHash": "0x..."
+}
 ```
 
 ### Important
 
-- Use `jv order protect` to add hedge to an **existing** position.
-- Do NOT use `jv order create --ppo` for this — that adds position size.
-- The CLI auto-detects position side (LONG/SHORT) from the order and selects the correct hedge type (PUT for LONG, CALL for SHORT).
+- Use `protect_order` to add hedge to an **existing** position.
+- Don't use `create_order` with `ppo: true` for this — that adds position size.
+- The tool auto-detects position side (LONG/SHORT) and selects the correct hedge type.
 
 ---
 
-## 3. Take-Profit (`jv tp set`)
+## 3. Take-Profit — `set_take_profit`
 
 Set a take-profit limit order for an existing position.
 
-### Syntax
-
-```
-jv tp set --order-id <id> --price <usdc> --symbol <symbol> [options]
-```
-
-### Options
-
-| Option | Required | Default | Description |
-|--------|----------|---------|-------------|
-| `--order-id <id>` | Yes | — | Existing order ID (position to close) |
-| `--price <usdc>` | Yes | — | Target price in USDC |
-| `--symbol <symbol>` | Yes | — | Asset symbol (e.g., `JBTC`) |
-| `--side <long\|short>` | No | `long` | Position side being closed |
-| `--ppo` | No | — | Enable PPO hedge on the TP order |
-| `--ppo-expire <duration>` | No | `30m` | PPO expiry: `30m` or `8h` |
-| `--ppo-category <ATM\|OTM>` | No | `ATM` | PPO option category |
-| `--ppo-tier <1-5>` | No | — | OTM strike offset tier |
-| `--network <name>` | No | `jaspervault` | Network name |
-| `--ttl <seconds>` | No | `86400` | Order TTL in seconds (default: 24h) |
-| `--pretty` | No | — | Pretty-print JSON output |
+### Parameters
 
-### Output
-
-```json
-{"success":true,"orderType":"limit","limitOrderId":"0x..."}
-```
+| Parameter | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `order_id` | Yes | — | Existing order ID |
+| `price` | Yes | — | Target price in USDC |
+| `symbol` | Yes | — | Asset symbol |
+| `side` | No | `long` | Position side being closed |
+| `ppo` | No | — | Enable PPO hedge on the TP order |
+| `ppo_expire` | No | `30m` | PPO expiry |
+| `ppo_category` | No | `ATM` | PPO category |
+| `ppo_tier` | No | — | OTM tier |
+| `ttl` | No | `86400` | Order TTL (default: 24h) |
 
 ### Example
 
-```bash
-# Set TP at $75,000 for a long position
-jv tp set --order-id 123 --price 75000 --symbol JBTC --pretty
-
-# Set TP for a short position
-jv tp set --order-id 456 --price 60000 --symbol JBTC --side short --pretty
+Set TP at $75,000 for a long position:
+```json
+{ "order_id": "123", "price": 75000, "symbol": "JBTC" }
 ```
 
 ---
 
-## 4. Stop-Loss (`jv sl set`)
-
-Set a stop-loss limit order for an existing position. Same options as `jv tp set`.
+## 4. Stop-Loss — `set_stop_loss`
 
-### Syntax
-
-```
-jv sl set --order-id <id> --price <usdc> --symbol <symbol> [options]
-```
-
-Options are identical to `jv tp set` (see above).
+Same parameters as `set_take_profit`. Set a stop-loss limit order for an existing position.
 
 ### Example
 
-```bash
-# Set SL at $65,000 for a long position
-jv sl set --order-id 123 --price 65000 --symbol JBTC --pretty
-
-# Set SL for a short position
-jv sl set --order-id 456 --price 80000 --symbol JBTC --side short --pretty
+Set SL at $65,000 for a long position:
+```json
+{ "order_id": "123", "price": 65000, "symbol": "JBTC" }
 ```
 
 ---
 
 ## 5. PPO (Perpetual Put Option) Details
 
-PPO provides hedge protection for positions. Key concepts:
-
 ### Option Categories
 
-| Category | Description | `--ppo-tier` |
-|----------|-------------|--------------|
+| Category | Description | `ppo_tier` |
+|----------|-------------|------------|
 | `ATM` (default) | At-the-money — strike = current price | Not needed |
 | `OTM` | Out-of-the-money — strike offset from current price | Required (1-5) |
 
 ### OTM Tiers
 
-| Tier | Strike Offset | Ratio |
-|------|---------------|-------|
-| 1 | 0.1% | 0.001 |
-| 2 | 0.2% | 0.002 |
-| 3 | 0.3% | 0.003 |
-| 4 | 0.4% | 0.004 |
-| 5 | 0.5% | 0.005 |
+| Tier | Strike Offset |
+|------|---------------|
+| 1 | 0.1% |
+| 2 | 0.2% |
+| 3 | 0.3% |
+| 4 | 0.4% |
+| 5 | 0.5% |
 
 ### Expiry Options
 
-| Duration | Seconds | Flag |
-|----------|---------|------|
-| 30 minutes (default) | 1800 | `--ppo-expire 30m` |
-| 8 hours | 28800 | `--ppo-expire 8h` |
+| Duration | Flag |
+|----------|------|
+| 30 minutes (default) | `ppo_expire: "30m"` |
+| 8 hours | `ppo_expire: "8h"` |
 
 ### Hedge Type (auto-selected)
 
@@ -248,27 +203,24 @@ PPO provides hedge protection for positions. Key concepts:
 
 ### Intent Mapping
 
-| User Says | Action | Command |
-|-----------|--------|---------|
-| "加保护" / "add protection" to existing | `jv order protect` | `jv order protect --order-id <id> --symbol JBTC` |
-| "开仓 + 保护" / "open with protection" | `jv order create --ppo` | `jv order create --side long -m 60 --symbol JBTC --ppo` |
-| "加仓 + 保护" / "add size with protection" | `jv order create --ppo` (same side) | `jv order create --side long -m 50 --symbol JBTC --ppo` |
-| "8小时" / "8 hour" | Add `--ppo-expire 8h` | |
-| "OTM" / "价外" | Add `--ppo-category OTM`, then ask for tier | |
-| "ATM" / "平价" or nothing | Default ATM, 30 min | |
-| "取消PPO" / "cancel PPO" / "remove hedge" | Order WITHOUT `--ppo` | See below |
-
-### PPO Cancellation (IMPORTANT)
-
-The smart contract **automatically cancels** existing PPO hedge options when you execute any position operation (reduce, close, add size) **without** the `--ppo` flag. There is **NO separate "cancel PPO" command**.
-
-| User Request | Correct Action | Command |
-|--------------|---------------|---------|
-| "减仓 + 取消PPO" | Single reduce order without `--ppo` | `jv order create --side <opposite> -m <amount> --symbol JBTC` |
-| "加仓 + 取消PPO" | Single add-size order without `--ppo` | `jv order create --side <same> -m <amount> --symbol JBTC` |
-| "平仓" (full close) | Close order without `--ppo` | `jv order create --side <opposite> -m <full_margin> --symbol JBTC` |
-| "减仓 + 保留PPO" | Reduce order WITH `--ppo` | `jv order create --side <opposite> -m <amount> --symbol JBTC --ppo` |
-
-**NEVER do this:**
-- Do NOT try to cancel PPO as a separate step. There is no "cancel PPO" command.
-- Do NOT send two orders when one suffices. "减仓 + 取消PPO" = ONE order without `--ppo`.
+| User Says | Tool | Parameters |
+|-----------|------|------------|
+| "add protection" to existing | `protect_order` | `{ order_id, symbol }` |
+| "open with protection" | `create_order` | `{ side, symbol, margin, ppo: true }` |
+| "add size with protection" | `create_order` (same side) | `{ side, symbol, margin, ppo: true }` |
+| "8 hours" | any PPO tool | add `ppo_expire: "8h"` |
+| "OTM" | any PPO tool | add `ppo_category: "OTM"`, then need `ppo_tier` |
+| "cancel PPO" / "remove hedge" | `create_order` | without `ppo` — see below |
+
+### PPO Cancellation
+
+The smart contract **automatically cancels** existing PPO when you execute any position operation without `ppo: true`. There is no separate "cancel PPO" tool.
+
+| User Request | Action | Parameters |
+|-------------|--------|------------|
+| "reduce + cancel PPO" | Single reduce order without `ppo` | `{ side: <opposite>, symbol, margin }` |
+| "add size + cancel PPO" | Single add-size order without `ppo` | `{ side: <same>, symbol, margin }` |
+| "close position" | Close order without `ppo` | `{ side: <opposite>, symbol, margin: <full> }` |
+| "reduce + keep PPO" | Reduce order WITH `ppo` | `{ side: <opposite>, symbol, margin, ppo: true }` |
+
+Never try to cancel PPO separately — there is no such tool. One order handles everything.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jaspervault_cli",
-  "version": "1.0.28",
+  "version": "1.0.30",
   "description": "JasperVault CLI for interacting with the JasperVault Manager API",
   "type": "module",
   "bin": {