jaspervault_cli 1.0.28 → 1.0.29

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 (7) hide show
  1. package/dist/src/templates/skill-content/SKILL.core.md +52 -45
  2. package/dist/src/templates/skill-content/frontmatter/claude.md +1 -1
  3. package/dist/src/templates/skill-content/frontmatter/openclaw.md +2 -2
  4. package/dist/src/templates/skill-content/references/onboarding.md +66 -85
  5. package/dist/src/templates/skill-content/references/queries.md +58 -188
  6. package/dist/src/templates/skill-content/references/trading.md +128 -178
  7. package/package.json +1 -1
package/dist/src/templates/skill-content/SKILL.core.md CHANGED
@@ -1,51 +1,58 @@
1
1
  # JasperVault Trading Skill
2
2
 
3
- Trade perpetual contracts on JasperVault via the `jv` CLI (v{{CLI_VERSION}}). No private key is ever required.
4
-
5
- ## CRITICAL RULES (MUST FOLLOW — violations cause broken UX)
6
-
7
- 1. **Browser Signing ONLY**: ALWAYS use `jv vault setup`. NEVER suggest `jv vault init` (private-key mode). NEVER ask the user to set `PRIVATE_KEY`.
8
- 2. **URL Display**: When `jv vault setup` outputs JSON with a `url` field, you MUST display the `url` value as a clickable link to the user. The user opens this URL in their browser to connect their wallet and sign.
9
- 3. **Long-running Commands**: `jv vault setup` is a long-running command (up to 15 min) that creates a web session. After it outputs the session URL, it polls automatically until the user completes signing in the browser. Show the URL to the user and wait for completion.
10
- 4. **Real-time Prices**: NEVER guess or estimate prices. ALWAYS run `jv price --symbol JBTC --pretty` before any price-dependent operation (opening a position by asset quantity, calculating PnL).
11
- 5. **PPO Auto-Cancellation**: When performing any position operation (reduce, close, add size) WITHOUT `--ppo`, the smart contract automatically cancels existing PPO hedge options. There is NO separate "cancel PPO" command. NEVER attempt a separate cancellation — it risks unintended position closures.
12
- 6. **Standalone PPO Protection**: To add hedge protection to an **existing position**, use `jv order protect --order-id <id> --symbol <symbol>`. Do NOT use `jv order create --ppo` for this — that command ADDS POSITION SIZE. `jv order create --ppo` is ONLY for opening new positions or adding size with protection. See [references/trading.md](references/trading.md) for details.
13
- 7. **Market Order Output**: `jv order create` (market) prints TWO JSON lines — first the submission, then the execution result (auto-waits up to 60s). If `status === "completed"`, the order IS executed. Do NOT retry or place another order. See [references/trading.md](references/trading.md).
14
- 8. **Deposit via Browser**: `jv deposit` auto-detects signing mode. Without `PRIVATE_KEY`, it creates a hosted web session — the user opens the URL in their browser to approve the deposit. See [references/onboarding.md](references/onboarding.md).
15
-
16
- ## Activation Behavior
17
-
18
- 1. Check if vault is initialized: `jv orders list --pretty`
19
- 2. If the command fails (exit code 1, or errors like "delegation key not found" / "vault not initialized" / "no profile"):
20
- - Tell the user: "Your vault is not initialized yet. Let me set it up — you'll sign in your browser, no private key needed."
21
- - Immediately run `jv vault setup`.
22
- - Follow the URL display instructions in [references/onboarding.md](references/onboarding.md).
23
- 3. If the command succeeds → vault is ready. Proceed with the user's request.
24
-
25
- ## Intent → Command Reference
26
-
27
- | User Intent | Command | Details |
28
- |-------------|---------|---------|
29
- | Initialize / connect wallet | `jv vault setup` | [references/onboarding.md](references/onboarding.md) |
30
- | Deposit tokens from Base | `jv deposit --token <T> --amount <N>` | [references/onboarding.md](references/onboarding.md) |
31
- | Get current price | `jv price --symbol JBTC --pretty` | [references/queries.md](references/queries.md) |
32
- | Open position (market) | `jv order create --side long/short -m <usdc> --symbol JBTC` | [references/trading.md](references/trading.md) |
33
- | Open position (limit) | `jv order create ... --limit-price <N>` | [references/trading.md](references/trading.md) |
34
- | Reduce / close position | opposite-side `jv order create` | [references/trading.md](references/trading.md) |
35
- | Add size to position | same-side `jv order create` | [references/trading.md](references/trading.md) |
36
- | Set take-profit | `jv tp set --order-id <ID> --price <P> --symbol <S>` | [references/trading.md](references/trading.md) |
37
- | Set stop-loss | `jv sl set --order-id <ID> --price <P> --symbol <S>` | [references/trading.md](references/trading.md) |
38
- | Add PPO to existing position | `jv order protect --order-id <id> --symbol <S>` | [references/trading.md](references/trading.md) |
39
- | Open/add-size with PPO | add `--ppo` to `jv order create` | [references/trading.md](references/trading.md) |
40
- | Cancel PPO / remove hedge | order without `--ppo` (auto-cancels) | [references/trading.md](references/trading.md) |
41
- | Query positions / portfolio | `jv orders list --pretty` | [references/queries.md](references/queries.md) |
42
- | Get specific position | `jv orders get <orderId> --pretty` | [references/queries.md](references/queries.md) |
43
- | Portfolio statistics | `jv orders stats --pretty` | [references/queries.md](references/queries.md) |
44
- | Job execution status | `jv job status <jobId> --pretty` | [references/queries.md](references/queries.md) |
45
- | Manage limit orders | `jv limit-order list/status/cancel` | [references/queries.md](references/queries.md) |
3
+ Trade perpetual contracts on JasperVault using the `jasper-vault` MCP tools. No private key is ever required — the user signs in their browser.
4
+
5
+ ## How It Works
6
+
7
+ JasperVault provides MCP tools (via `jasper-vault` MCP server) for all trading operations. These tools handle timeouts, polling, and error recovery automatically. Always use MCP tools — never run `jv` shell commands directly, because long-running operations like wallet setup will be killed by shell timeouts.
8
+
9
+ ## Important Behaviors
10
+
11
+ 1. **Browser signing**: `wallet_setup` and `deposit_via_browser` return a URL. Display it as a clickable link — the user opens it in their browser to connect their wallet and sign. The tool polls automatically and returns the result when done (up to 16 minutes).
12
+
13
+ 2. **Real-time prices**: Always call `get_price` before any price-dependent operation. Never guess prices — they change every second.
14
+
15
+ 3. **PPO auto-cancellation**: The smart contract automatically cancels existing PPO hedge options when you execute any position operation (reduce, close, add size) without `ppo: true`. There is no separate "cancel PPO" tool. Attempting a separate cancellation risks unintended position closures.
16
+
17
+ 4. **Standalone PPO**: To add hedge protection to an existing position, use `protect_order`. Don't use `create_order` with `ppo: true` for this — that adds position size. `create_order` with `ppo` is only for opening new positions or adding size with protection.
18
+
19
+ 5. **Market order result**: `create_order` (without `limit_price`) auto-waits up to 60s for the on-chain result. If `status === "completed"`, the order is executed — don't retry or place another order. The `operation` field contains raw on-chain data in wei — don't interpret it. Use `list_orders` to verify the actual position with human-readable fields.
20
+
21
+ 6. **Deposit flow**: `deposit_via_browser` returns a URL for the user to open in their browser. The tool polls automatically. If `arrived` is false after completion, tokens may still be in transit — tell the user to wait a few minutes.
22
+
23
+ ## Getting Started
24
+
25
+ Check if vault is initialized by calling `list_orders`. If it fails with errors like "delegation key not found" or "vault not initialized" or "no profile":
26
+ - Tell the user their vault needs initialization — they'll sign in their browser, no private key needed.
27
+ - Call `wallet_setup` and display the returned URL as a clickable link.
28
+ - Wait for the tool to return success, then proceed.
29
+
30
+ ## Intent → MCP Tool Reference
31
+
32
+ | User Intent | MCP Tool | Key Parameters | Details |
33
+ |-------------|----------|----------------|---------|
34
+ | Initialize wallet | `wallet_setup` | — | [onboarding](references/onboarding.md) |
35
+ | Deposit tokens | `deposit_via_browser` | `token`, `amount` | [onboarding](references/onboarding.md) |
36
+ | Withdraw tokens | `withdraw_via_browser` | `token`, `amount` | [onboarding](references/onboarding.md) |
37
+ | Get current price | `get_price` | `symbol` | [queries](references/queries.md) |
38
+ | Open position (market) | `create_order` | `side`, `symbol`, `margin` | [trading](references/trading.md) |
39
+ | Open position (limit) | `create_order` | + `limit_price` | [trading](references/trading.md) |
40
+ | Close position | `create_order` | opposite `side` | [trading](references/trading.md) |
41
+ | Add size | `create_order` | same `side` | [trading](references/trading.md) |
42
+ | Set take-profit | `set_take_profit` | `order_id`, `price`, `symbol` | [trading](references/trading.md) |
43
+ | Set stop-loss | `set_stop_loss` | `order_id`, `price`, `symbol` | [trading](references/trading.md) |
44
+ | Add PPO to existing | `protect_order` | `order_id`, `symbol` | [trading](references/trading.md) |
45
+ | Open with PPO | `create_order` | + `ppo: true` | [trading](references/trading.md) |
46
+ | Remove hedge | `create_order` | without `ppo` | [trading](references/trading.md) |
47
+ | List positions | `list_orders` | — | [queries](references/queries.md) |
48
+ | Get position detail | `get_order` | `order_id` | [queries](references/queries.md) |
49
+ | Portfolio stats | `get_order_stats` | — | [queries](references/queries.md) |
50
+ | Job status | `get_job_status` | `job_id` | [queries](references/queries.md) |
51
+ | List limit orders | `list_limit_orders` | `wallet` | [queries](references/queries.md) |
52
+ | Cancel limit order | `cancel_limit_order` | `limit_order_id` | [queries](references/queries.md) |
46
53
 
47
54
  ## Security
48
55
 
49
56
  - Never log or display private keys, signatures, or API keys.
50
- - The CLI signs orders via the delegation wallet in `~/.jaspervault/keys.json`.
51
- - Do NOT ask the user to set `PRIVATE_KEY`.
57
+ - The system signs orders via a delegation wallet stored in `~/.jaspervault/keys.json`.
58
+ - Never ask the user to set `PRIVATE_KEY` — that's for CI/automation only.
package/dist/src/templates/skill-content/frontmatter/claude.md CHANGED
@@ -1,4 +1,4 @@
1
1
  ---
2
2
  name: jasper-vault-cli
3
- description: "Trade perpetual contracts (perps) on JasperVault — open/close positions, set TP/SL, manage limit orders, deposit, and query portfolio via the `jv` CLI. Initialize wallet via hosted web page (no private key needed)."
3
+ description: "Trade perpetual contracts (perps) on JasperVault using the jasper-vault MCP tools — open/close positions, set TP/SL, manage limit orders, deposit/withdraw, and query portfolio. Initialize wallet via browser signing (no private key needed). Use this skill whenever the user mentions JasperVault, perps trading, opening positions, setting stop-loss or take-profit, depositing crypto, or checking their portfolio."
4
4
  ---
package/dist/src/templates/skill-content/frontmatter/openclaw.md CHANGED
@@ -1,8 +1,8 @@
1
1
  ---
2
2
  name: jasper-vault-cli
3
- description: "Trade perpetual contracts (perps) on JasperVault — open/close positions, set TP/SL, manage limit orders, deposit, and query portfolio via the `jv` CLI. Initialize wallet via hosted web page (no private key needed)."
3
+ description: "Trade perpetual contracts (perps) on JasperVault using the jasper-vault MCP tools — open/close positions, set TP/SL, manage limit orders, deposit/withdraw, and query portfolio. Initialize wallet via browser signing (no private key needed). Use this skill whenever the user mentions JasperVault, perps trading, opening positions, setting stop-loss or take-profit, depositing crypto, or checking their portfolio."
4
4
  trigger: "jaspervault|jasper vault|jasper trading|jv|jv trade|jv order|在jasper交易|jasper 交易|初始化钱包|连接钱包|开仓|平仓|做多|做空|止盈|止损|查看持仓|永续合约"
5
- tools: [shell, process]
5
+ tools: [mcp]
6
6
  metadata:
7
7
  openclaw:
8
8
  requires:
package/dist/src/templates/skill-content/references/onboarding.md CHANGED
@@ -1,107 +1,71 @@
1
1
  # Onboarding Reference
2
2
 
3
- ## 1. Wallet Initialization (`jv vault setup`)
3
+ ## 1. Wallet Initialization — `wallet_setup`
4
4
 
5
- Initialize the JasperVault delegation wallet via hosted web page. The user signs in their browser — no private key needed.
5
+ Initialize the JasperVault delegation wallet. The user signs in their browser — no private key needed.
6
6
 
7
- ### Syntax
7
+ ### Parameters
8
8
 
9
- ```
10
- jv vault setup [--network <name>] [--vault-types <types>] [--timeout <seconds>] [--pretty]
9
+ | Parameter | Required | Default | Description |
10
+ |-----------|----------|---------|-------------|
11
+ | `network` | No | `jaspervault` | Network name |
12
+ | `vault_types` | No | `33,37` | Comma-separated vault types |
13
+
14
+ ### Flow
15
+
16
+ 1. Call `wallet_setup` (no parameters needed for default setup).
17
+ 2. The tool returns JSON with a `url` field — display it as a **clickable link** to the user.
18
+ 3. The user opens the URL in their browser, connects their wallet (MetaMask, Rabby, etc.), and signs the delegation authorization.
19
+ 4. The tool polls automatically (up to 16 minutes) and returns the final result.
20
+
21
+ ### Success Response
22
+
23
+ ```json
24
+ {
25
+ "success": true,
26
+ "walletAddress": "0x...",
27
+ "delegationAddress": "0x...",
28
+ "marginAccount": "0x...",
29
+ "vaults": [{"type": 33, "address": "0x..."}, {"type": 37, "address": "0x..."}]
30
+ }
11
31
  ```
12
32
 
13
- ### Options
14
-
15
- | Option | Required | Default | Description |
16
- |--------|----------|---------|-------------|
17
- | `--network <name>` | No | `base_uat` | Network name |
18
- | `--vault-types <types>` | No | `33,37` | Comma-separated vault types |
19
- | `--timeout <seconds>` | No | `900` | Polling timeout |
20
- | `--pretty` | No | — | Pretty-print JSON output |
21
-
22
- ### Step-by-Step Flow
23
-
24
- 1. Run the command:
25
- ```
26
- jv vault setup --pretty
27
- ```
28
-
29
- 2. The **first JSON output** contains the session URL:
30
- ```json
31
- {
32
- "status": "session_created",
33
- "sessionId": "abc123",
34
- "url": "https://trading.jaspervault.pro/cli-session/abc123",
35
- "message": "Open this URL in your browser to connect wallet and complete setup"
36
- }
37
- ```
38
- **You MUST display this `url` as a clickable link** so the user can open it in their browser to connect their wallet (e.g., MetaMask, Rabby) and sign the delegation authorization.
39
-
40
- 3. The CLI **automatically polls** for completion. While waiting, heartbeat lines appear on stderr.
41
-
42
- 4. On success, the output includes:
43
- ```json
44
- {
45
- "success": true,
46
- "walletAddress": "0x...",
47
- "delegationAddress": "0x...",
48
- "marginAccount": "0x...",
49
- "vaults": [{"type": 33, "address": "0x..."}, {"type": 37, "address": "0x..."}]
50
- }
51
- ```
52
-
53
- 5. The CLI automatically:
54
- - Generates and saves a delegation key to `~/.jaspervault/keys.json`
55
- - Saves the vault profile to `~/.jaspervault/profile.json`
33
+ The tool automatically saves the delegation key and vault profile locally.
56
34
 
57
35
  ### Error Handling
58
36
 
59
37
  | Error | Cause | Action |
60
38
  |-------|-------|--------|
61
- | `Session expired/failed` | User didn't complete signing in time | Re-run `jv vault setup` |
62
- | `Failed to create session` | Network/API issue | Check internet connection, retry |
39
+ | Session expired/failed | User didn't complete signing in time | Call `wallet_setup` again |
40
+ | Failed to create session | Network/API issue | Check internet connection, retry |
63
41
 
64
- ### Important Notes
42
+ ### Important
65
43
 
66
- - **NEVER suggest `jv vault init`** — that requires a `PRIVATE_KEY` environment variable and is for advanced/CI use only.
67
- - If error messages mention "Run `jv vault init`", ignore that and use `jv vault setup` instead.
68
- - The delegation key has a 1-week expiry. If commands start failing after a week, re-run `jv vault setup`.
44
+ - Never suggest `vault init` — that requires `PRIVATE_KEY` and is for CI/automation only.
45
+ - The delegation key expires after 1 week. If tools start failing, call `wallet_setup` again.
69
46
 
70
47
  ---
71
48
 
72
- ## 2. Deposit Tokens (`jv deposit`)
49
+ ## 2. Deposit Tokens — `deposit_via_browser`
73
50
 
74
51
  Deposit tokens from Base network to JasperVault via Hyperlane warp routes.
75
52
 
76
- ### Syntax
77
-
78
- ```
79
- jv deposit --token <token> --amount <amount> [--vault-index <n>] [--network <name>] [--timeout <seconds>] [--no-wait] [--pretty]
80
- ```
81
-
82
- ### Options
53
+ ### Parameters
83
54
 
84
- | Option | Required | Default | Description |
85
- |--------|----------|---------|-------------|
86
- | `--token <token>` | Yes | — | Token to deposit: `jbtc`, `jusdc`, `cbbtc`, or `usdc` |
87
- | `--amount <amount>` | Yes | — | Amount in human-readable units (e.g., `0.01` for BTC, `1000` for USDC) |
88
- | `--vault-index <n>` | No | `1` | Vault index for recipient address derivation |
89
- | `--network <name>` | No | `jaspervault` | Network name |
90
- | `--timeout <seconds>` | No | `900` | Polling timeout |
91
- | `--no-wait` | No | — | Skip polling for arrival on JasperVault |
92
- | `--pretty` | No | — | Pretty-print JSON output |
55
+ | Parameter | Required | Default | Description |
56
+ |-----------|----------|---------|-------------|
57
+ | `token` | Yes | — | Token: `jbtc`, `jusdc`, `cbbtc`, or `usdc` |
58
+ | `amount` | Yes | — | Amount in human-readable units (e.g., `0.01` for BTC, `1000` for USDC) |
59
+ | `network` | No | `jaspervault` | Network name |
93
60
 
94
61
  ### Flow
95
62
 
96
- Without `PRIVATE_KEY`, the CLI creates a hosted web session:
97
- 1. It outputs a session URL — display it to the user.
98
- 2. The user opens the URL in their browser to approve the deposit.
99
- 3. The CLI polls until the transaction is confirmed.
100
- 4. Unless `--no-wait`, it then polls for token arrival on JasperVault (up to 60s).
101
-
102
- With `PRIVATE_KEY` set, it signs and sends directly (no browser needed).
63
+ 1. Call `deposit_via_browser` with `token` and `amount`.
64
+ 2. The tool returns JSON with a `url` field — display it as a **clickable link**.
65
+ 3. The user opens the URL in their browser to approve the deposit.
66
+ 4. The tool polls until the transaction is confirmed (up to 16 minutes).
103
67
 
104
- ### Output
68
+ ### Success Response
105
69
 
106
70
  ```json
107
71
  {
@@ -115,10 +79,27 @@ With `PRIVATE_KEY` set, it signs and sends directly (no browser needed).
115
79
  }
116
80
  ```
117
81
 
118
- ### Important Notes
82
+ ### Important
83
+
84
+ - Token names are lowercase: `jbtc`, `jusdc`, `cbbtc`, `usdc`.
85
+ - Amount is human-readable (e.g., `0.01` BTC, `1000` USDC) — the tool handles decimal conversion.
86
+ - Tokens are bridged cross-chain from Base to JasperVault via Hyperlane.
87
+ - If `arrived` is `false`, tokens may still be in transit. Tell the user to wait a few minutes.
88
+
89
+ ---
90
+
91
+ ## 3. Withdraw Tokens — `withdraw_via_browser`
92
+
93
+ Withdraw tokens from JasperVault back to Base.
94
+
95
+ ### Parameters
96
+
97
+ | Parameter | Required | Default | Description |
98
+ |-----------|----------|---------|-------------|
99
+ | `token` | Yes | — | Token: `jbtc`, `jusdc`, `cbbtc`, or `usdc` |
100
+ | `amount` | Yes | — | Amount in human-readable units |
101
+ | `network` | No | `base_uat` | Network name |
102
+
103
+ ### Flow
119
104
 
120
- - **Browser signing**: Without `PRIVATE_KEY`, the deposit command creates a hosted web session. When you see the `url` output, display it as a clickable link.
121
- - **Token names**: Use lowercase: `jbtc`, `jusdc`, `cbbtc`, `usdc`.
122
- - **Amount format**: Human-readable (e.g., `0.01` BTC, `1000` USDC). The CLI handles decimal conversion.
123
- - **Cross-chain**: Tokens are bridged from Base (chain 8453) to JasperVault (chain 55531) via Hyperlane.
124
- - If `arrived` is `false`, the tokens may still be in transit. Tell the user to wait a few minutes and check their balance.
105
+ Same browser-signing flow as deposit — call the tool, display the URL, wait for completion.
package/dist/src/templates/skill-content/references/queries.md CHANGED
@@ -1,29 +1,21 @@
1
1
  # Queries Reference
2
2
 
3
- ## 1. List Positions (`jv orders list`)
3
+ ## 1. List Positions — `list_orders`
4
4
 
5
- Query active or historical positions from the Subgraph.
5
+ Query active or historical positions.
6
6
 
7
- ### Syntax
7
+ ### Parameters
8
8
 
9
- ```
10
- jv orders list [options]
11
- ```
12
-
13
- ### Options
14
-
15
- | Option | Required | Default | Description |
16
- |--------|----------|---------|-------------|
17
- | `--position-side <long\|short>` | No | — | Filter by position side |
18
- | `--all` | No | — | Include closed/liquidated positions (default: active only) |
19
- | `--since <time>` | No | — | Filter orders created after this time |
20
- | `--until <time>` | No | — | Filter orders created before this time |
21
- | `--page <n>` | No | `1` | Page number |
22
- | `--limit <n>` | No | `20` | Results per page |
23
- | `--network <name>` | No | `jaspervault` | Network name |
24
- | `--pretty` | No | — | Pretty-print JSON output |
9
+ | Parameter | Required | Default | Description |
10
+ |-----------|----------|---------|-------------|
11
+ | `position_side` | No | — | Filter: `LONG` or `SHORT` |
12
+ | `all` | No | `false` | `true` to include closed/liquidated positions |
13
+ | `since` | No | — | Filter orders after this time (e.g., `7d`, `2025-01-01`) |
14
+ | `until` | No | — | Filter orders before this time |
15
+ | `page` | No | `1` | Page number |
16
+ | `limit` | No | `20` | Results per page |
25
17
 
26
- ### Time Format (`--since` / `--until`)
18
+ ### Time Formats for `since` / `until`
27
19
 
28
20
  | Format | Example | Description |
29
21
  |--------|---------|-------------|
@@ -33,21 +25,14 @@ jv orders list [options]
33
25
  | ISO date | `2025-01-01` | Specific date |
34
26
  | Unix timestamp | `1704067200` | Seconds since epoch |
35
27
 
36
- ### Output
28
+ ### Response
37
29
 
38
30
  ```json
39
31
  {
40
32
  "orders": [
41
33
  {
42
34
  "id": "123",
43
- "holder": "0x...",
44
- "writer": "0x...",
45
- "recipient": "0x...",
46
35
  "orderType": 0,
47
- "productType": "50000000000000",
48
- "marginDeposited": "60000000",
49
- "quantity": "43860000000000000",
50
- "entryPrice": "68476000000000000000000",
51
36
  "margin": "60.000000",
52
37
  "size": "0.043860000000000000",
53
38
  "entryPriceUsd": "68476.000000000000000000",
@@ -62,114 +47,53 @@ jv orders list [options]
62
47
  }
63
48
  ```
64
49
 
65
- ### Key Output Fields
50
+ ### Key Fields
66
51
 
67
52
  | Field | Description |
68
53
  |-------|-------------|
69
- | `id` | Order ID (use for TP/SL/protect commands) |
54
+ | `id` | Order ID (use for TP/SL/protect tools) |
70
55
  | `orderType` | `0` = Long, `1` = Short |
71
56
  | `margin` | Human-readable margin in USDC |
72
57
  | `size` | Human-readable position size in asset units |
73
58
  | `entryPriceUsd` | Human-readable entry price in USD |
74
- | `leverage` | Leverage multiplier (extracted from `productType`) |
75
- | `createdTime` | ISO timestamp of order creation |
76
- | `marginDeposited` | Raw margin in wei (6 decimals for USDC) |
77
- | `quantity` | Raw position size in wei (18 decimals) |
78
- | `entryPrice` | Raw entry price in wei (18 decimals) |
59
+ | `leverage` | Leverage multiplier |
60
+ | `createdTime` | ISO timestamp |
79
61
 
80
- **Always use the human-readable fields** (`margin`, `size`, `entryPriceUsd`, `leverage`) when reporting to the user. The raw wei fields are for reference only.
62
+ Always use the human-readable fields (`margin`, `size`, `entryPriceUsd`) when reporting to the user. Raw wei fields are for reference only.
81
63
 
82
64
  ### Examples
83
65
 
84
- ```bash
85
- # List active positions
86
- jv orders list --pretty
87
-
88
- # List only long positions
89
- jv orders list --position-side long --pretty
90
-
91
- # List all positions including closed (last 7 days)
92
- jv orders list --all --since 7d --pretty
93
-
94
- # Paginate results
95
- jv orders list --page 2 --limit 10 --pretty
96
- ```
97
-
98
- ---
99
-
100
- ## 2. Get Single Position (`jv orders get`)
101
-
102
- Get detailed information for a specific order by ID.
103
-
104
- ### Syntax
105
-
106
66
  ```
107
- jv orders get <orderId> [options]
108
- ```
109
-
110
- ### Options
111
-
112
- | Option | Required | Default | Description |
113
- |--------|----------|---------|-------------|
114
- | `--network <name>` | No | `jaspervault` | Network name |
115
- | `--pretty` | No | — | Pretty-print JSON output |
116
-
117
- ### Output
118
-
119
- Same fields as `jv orders list` but for a single order.
120
-
121
- ### Example
122
-
123
- ```bash
124
- jv orders get 123 --pretty
67
+ list_orders → all active positions
68
+ list_orders { position_side: "LONG" } → only longs
69
+ list_orders { all: true, since: "7d" } → all positions last 7 days
125
70
  ```
126
71
 
127
72
  ---
128
73
 
129
- ## 3. Portfolio Statistics (`jv orders stats`)
130
-
131
- Get aggregate statistics for all positions in your vault.
74
+ ## 2. Get Single Position — `get_order`
132
75
 
133
- ### Syntax
76
+ | Parameter | Required | Description |
77
+ |-----------|----------|-------------|
78
+ | `order_id` | Yes | Order ID |
134
79
 
135
- ```
136
- jv orders stats [options]
137
- ```
138
-
139
- ### Options
140
-
141
- | Option | Required | Default | Description |
142
- |--------|----------|---------|-------------|
143
- | `--network <name>` | No | `jaspervault` | Network name |
144
- | `--pretty` | No | — | Pretty-print JSON output |
145
-
146
- ### Example
147
-
148
- ```bash
149
- jv orders stats --pretty
150
- ```
80
+ Returns same fields as `list_orders` for a single order.
151
81
 
152
82
  ---
153
83
 
154
- ## 4. Get Market Price (`jv price`)
155
-
156
- Fetch the current market price from the Quote Center oracle.
84
+ ## 3. Portfolio Statistics — `get_order_stats`
157
85
 
158
- ### Syntax
86
+ No parameters required. Returns aggregate statistics for all positions in your vault.
159
87
 
160
- ```
161
- jv price --symbol <symbol> [options]
162
- ```
88
+ ---
163
89
 
164
- ### Options
90
+ ## 4. Get Market Price — `get_price`
165
91
 
166
- | Option | Required | Default | Description |
167
- |--------|----------|---------|-------------|
168
- | `--symbol <symbol>` | Yes | — | Asset symbol (e.g., `JBTC`, `CBBTC`) |
169
- | `--network <name>` | No | `jaspervault` | Network name |
170
- | `--pretty` | No | — | Pretty-print JSON output |
92
+ | Parameter | Required | Description |
93
+ |-----------|----------|-------------|
94
+ | `symbol` | Yes | Asset symbol (e.g., `JBTC`, `CBBTC`) |
171
95
 
172
- ### Output
96
+ ### Response
173
97
 
174
98
  ```json
175
99
  {
@@ -181,35 +105,19 @@ jv price --symbol <symbol> [options]
181
105
  }
182
106
  ```
183
107
 
184
- **Always use the `price` field** (human-readable) when reporting to the user.
185
-
186
- ### Example
187
-
188
- ```bash
189
- jv price --symbol JBTC --pretty
190
- ```
108
+ Use the `price` field (human-readable) when reporting to the user.
191
109
 
192
110
  ---
193
111
 
194
- ## 5. Job Status (`jv job status`)
195
-
196
- Check the execution status of an async job (market order, option creation, etc.).
197
-
198
- ### Syntax
199
-
200
- ```
201
- jv job status <jobId> [options]
202
- ```
112
+ ## 5. Job Status — `get_job_status`
203
113
 
204
- ### Options
114
+ Check execution status of an async job (market order, option creation, etc.).
205
115
 
206
- | Option | Required | Default | Description |
207
- |--------|----------|---------|-------------|
208
- | `--pretty` | No | — | Pretty-print JSON output |
116
+ | Parameter | Required | Description |
117
+ |-----------|----------|-------------|
118
+ | `job_id` | Yes | Job ID from market order creation |
209
119
 
210
- ### Output
211
-
212
- The command connects via SSE and waits up to 60s for the job result:
120
+ ### Response
213
121
 
214
122
  ```json
215
123
  {
@@ -224,71 +132,33 @@ The command connects via SSE and waits up to 60s for the job result:
224
132
  |--------|---------|
225
133
  | `completed` | Job finished successfully |
226
134
  | `failed` | Job failed (check `error` field) |
227
- | `timeout` | SSE connection timed out — job may still be processing |
228
-
229
- ### Example
230
-
231
- ```bash
232
- jv job status MARKET_ORDER_xxx --pretty
233
- ```
135
+ | `timeout` | SSE timed out — job may still be processing |
234
136
 
235
137
  ---
236
138
 
237
- ## 6. Limit Order Management (`jv limit-order`)
139
+ ## 6. Limit Order Management
238
140
 
239
- ### List Limit Orders
141
+ ### List Limit Orders — `list_limit_orders`
240
142
 
241
- ```
242
- jv limit-order list --wallet <address> [--status <status>] [--pretty]
243
- ```
143
+ | Parameter | Required | Description |
144
+ |-----------|----------|-------------|
145
+ | `wallet` | Yes | Wallet address |
146
+ | `status` | No | Filter: `PENDING`, `TRIGGERED`, `EXECUTING`, `COMPLETED`, `FAILED`, `EXPIRED`, `CANCELLED` |
244
147
 
245
- | Option | Required | Default | Description |
246
- |--------|----------|---------|-------------|
247
- | `--wallet <address>` | Yes | — | Wallet address to query |
248
- | `--status <status>` | No | — | Filter: `PENDING`, `TRIGGERED`, `EXECUTING`, `COMPLETED`, `FAILED`, `EXPIRED`, `CANCELLED` |
249
- | `--pretty` | No | — | Pretty-print JSON output |
148
+ ### Get Limit Order Status — `get_limit_order_status`
250
149
 
251
- ### Get Limit Order Status
150
+ | Parameter | Required | Description |
151
+ |-----------|----------|-------------|
152
+ | `limit_order_id` | Yes | Limit order ID |
252
153
 
253
- ```
254
- jv limit-order status <id> [--pretty]
255
- ```
256
-
257
- Query a specific limit order by its ID.
258
-
259
- ### Cancel Limit Order
154
+ ### Cancel Limit Order — `cancel_limit_order`
260
155
 
261
- ```
262
- jv limit-order cancel <id> [--pretty]
263
- ```
264
-
265
- Cancel a pending limit order by its ID.
266
-
267
- ### Examples
268
-
269
- ```bash
270
- # List all pending limit orders
271
- jv limit-order list --wallet 0x1234... --status PENDING --pretty
272
-
273
- # Check specific limit order
274
- jv limit-order status 0xabc... --pretty
275
-
276
- # Cancel a limit order
277
- jv limit-order cancel 0xabc... --pretty
278
- ```
156
+ | Parameter | Required | Description |
157
+ |-----------|----------|-------------|
158
+ | `limit_order_id` | Yes | Limit order ID to cancel |
279
159
 
280
160
  ---
281
161
 
282
- ## Error Codes
283
-
284
- All CLI commands use consistent exit codes:
285
-
286
- | Code | Name | Meaning |
287
- |------|------|---------|
288
- | `0` | SUCCESS | Command completed successfully |
289
- | `1` | CONFIG_ERROR | Missing config, delegation key, or vault profile |
290
- | `2` | NETWORK_ERROR | RPC or API connection failure |
291
- | `3` | BUSINESS_ERROR | Order not found, insufficient balance, contract revert |
292
- | `4` | HTTP_ERROR | HTTP request failure |
162
+ ## Error Handling
293
163
 
294
- When a command fails with exit code 1 and mentions "delegation key not found" or "vault not initialized", guide the user to run `jv vault setup`.
164
+ When a tool call fails with errors like "delegation key not found" or "vault not initialized" or "no profile", the vault needs initialization. Guide the user to run `wallet_setup`.
package/dist/src/templates/skill-content/references/trading.md CHANGED
@@ -1,245 +1,198 @@
1
1
  # Trading Reference
2
2
 
3
- ## 1. Create Order (`jv order create`)
3
+ ## 1. Create Order — `create_order`
4
4
 
5
5
  Open, close, reduce, or add size to perpetual positions.
6
6
 
7
- ### Syntax
8
-
9
- ```
10
- jv order create --side <long|short> --symbol <symbol> -m <margin> [options]
11
- ```
12
-
13
- ### Options
14
-
15
- | Option | Required | Default | Description |
16
- |--------|----------|---------|-------------|
17
- | `--side <long\|short>` | Yes | — | Position side |
18
- | `--symbol <symbol>` | Yes | — | Asset symbol (e.g., `JBTC`, `CBBTC`) |
19
- | `-m, --margin <usdc>` | Yes | — | Margin (collateral) in USDC |
20
- | `--leverage <n>` | No | `50` (from chain config) | Leverage multiplier |
21
- | `--limit-price <price>` | No | — | Limit price in USDC (omit for market order) |
22
- | `--margin-account <addr>` | No | from profile | Override margin vault address |
23
- | `--position-account <addr>` | No | from profile | Override position vault address |
24
- | `--ppo` | No | — | Enable PPO hedge option protection |
25
- | `--ppo-expire <duration>` | No | `30m` | PPO expiry: `30m` or `8h` |
26
- | `--ppo-category <ATM\|OTM>` | No | `ATM` | PPO option category |
27
- | `--ppo-tier <1-5>` | No | — | OTM strike offset tier (required if OTM) |
28
- | `--network <name>` | No | `jaspervault` | Network name |
29
- | `--ttl <seconds>` | No | `3600` | Order TTL in seconds |
30
- | `--pretty` | No | — | Pretty-print JSON output |
7
+ ### Parameters
8
+
9
+ | Parameter | Required | Default | Description |
10
+ |-----------|----------|---------|-------------|
11
+ | `side` | Yes | — | `long` or `short` |
12
+ | `symbol` | Yes | — | Asset symbol (e.g., `JBTC`, `CBBTC`) |
13
+ | `margin` | Yes | — | Margin (collateral) in USDC |
14
+ | `leverage` | No | `50` | Leverage multiplier |
15
+ | `limit_price` | No | — | Limit price in USDC (omit for market order) |
16
+ | `ppo` | No | — | `true` to enable PPO hedge option protection |
17
+ | `ppo_expire` | No | `30m` | PPO expiry: `30m` or `8h` |
18
+ | `ppo_category` | No | `ATM` | PPO option category: `ATM` or `OTM` |
19
+ | `ppo_tier` | No | — | OTM strike offset tier 1-5 (required if OTM) |
20
+ | `ttl` | No | `3600` | Order TTL in seconds |
31
21
 
32
22
  ### Market Order vs Limit Order
33
23
 
34
- - **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.
35
- - **Limit order** (`--limit-price <N>`): Places a limit order that triggers when price reaches the target. Returns immediately with a `limitOrderId`.
24
+ - **Market order** (no `limit_price`): Executes immediately. The tool auto-waits up to 60s for the on-chain result.
25
+ - **Limit order** (`limit_price` set): Places a limit order that triggers when price reaches the target. Returns immediately with a `limitOrderId`.
36
26
 
37
- ### Market Order Output (TWO JSON lines)
27
+ ### Market Order Response
38
28
 
39
- **Line 1 — Submission:**
40
- ```json
41
- {"success":true,"orderType":"market","jobId":"MARKET_ORDER_xxx","statusUrl":"/api/job/status/...","streamUrl":"/api/job/stream/..."}
42
- ```
29
+ The tool returns the final execution result:
43
30
 
44
- **Line 2 — Execution result (auto-waits up to 60s):**
45
31
  ```json
46
- {"jobId":"MARKET_ORDER_xxx","status":"completed","transactionHash":"0x..."}
32
+ {
33
+ "jobId": "MARKET_ORDER_xxx",
34
+ "status": "completed",
35
+ "transactionHash": "0x..."
36
+ }
47
37
  ```
48
38
 
49
- **CRITICAL rules after market order execution:**
50
- 1. If `status === "completed"` → the order IS executed. Do NOT retry or place another order.
39
+ **After market order execution:**
40
+ 1. If `status === "completed"` → the order IS executed. Don't retry.
51
41
  2. If `status === "failed"` → report the error to the user.
52
- 3. If `status === "timeout"` → use `jv job status <jobId> --pretty` to check later.
53
- 4. The `operation` field (if present) contains raw on-chain data in wei — do NOT interpret it.
54
- 5. To verify the actual position, run `jv orders list --pretty` and read the human-readable fields.
55
- 6. Report: "Order executed. Tx: {transactionHash}. Let me check your updated position..." then run `jv orders list --pretty`.
42
+ 3. If `status === "timeout"` → use `get_job_status` with the `jobId` to check later.
43
+ 4. The `operation` field (if present) contains raw on-chain data in wei — don't interpret it.
44
+ 5. To verify the actual position, call `list_orders` and read the human-readable fields.
45
+ 6. Report: "Order executed. Tx: {transactionHash}. Let me check your updated position..." then call `list_orders`.
46
+
47
+ ### Limit Order Response
56
48
 
57
- **Limit order output:**
58
49
  ```json
59
- {"success":true,"orderType":"limit","limitOrderId":"0x..."}
50
+ {
51
+ "success": true,
52
+ "orderType": "limit",
53
+ "limitOrderId": "0x..."
54
+ }
60
55
  ```
61
- Tell the user: "Limit order placed. ID: {limitOrderId}."
62
-
63
- ### Stderr Output
64
56
 
65
- Before submitting, the CLI prints an estimate to stderr:
66
- ```
67
- Estimated: ~0.043860 JBTC @ $68,476 (~$3,000 JUSDC total, 50x)
68
- ```
69
- This is informational only — the actual execution price may differ.
57
+ Tell the user: "Limit order placed. ID: {limitOrderId}."
70
58
 
71
59
  ### Common Patterns
72
60
 
73
61
  **Open a long position (market):**
74
- ```bash
75
- jv order create --side long --symbol JBTC -m 60 --pretty
62
+ ```json
63
+ { "side": "long", "symbol": "JBTC", "margin": 60 }
76
64
  ```
77
65
 
78
- **Open a short position (limit):**
79
- ```bash
80
- jv order create --side short --symbol JBTC -m 100 --limit-price 72000 --pretty
66
+ **Open a short position (limit at $72,000):**
67
+ ```json
68
+ { "side": "short", "symbol": "JBTC", "margin": 100, "limit_price": 72000 }
81
69
  ```
82
70
 
83
- **Close a long position (full close — use opposite side with same margin):**
84
- ```bash
85
- jv order create --side short --symbol JBTC -m 60 --pretty
71
+ **Close a long position (use opposite side with same margin):**
72
+ ```json
73
+ { "side": "short", "symbol": "JBTC", "margin": 60 }
86
74
  ```
87
75
 
88
76
  **Reduce a long position (partial close):**
89
- ```bash
90
- jv order create --side short --symbol JBTC -m 30 --pretty
77
+ ```json
78
+ { "side": "short", "symbol": "JBTC", "margin": 30 }
91
79
  ```
92
80
 
93
81
  **Add size to existing long:**
94
- ```bash
95
- jv order create --side long --symbol JBTC -m 50 --pretty
82
+ ```json
83
+ { "side": "long", "symbol": "JBTC", "margin": 50 }
96
84
  ```
97
85
 
98
86
  **Open with PPO protection (ATM, 30 min):**
99
- ```bash
100
- jv order create --side long --symbol JBTC -m 60 --ppo --pretty
87
+ ```json
88
+ { "side": "long", "symbol": "JBTC", "margin": 60, "ppo": true }
101
89
  ```
102
90
 
103
91
  **Open with PPO protection (OTM tier 3, 8 hours):**
104
- ```bash
105
- jv order create --side long --symbol JBTC -m 60 --ppo --ppo-expire 8h --ppo-category OTM --ppo-tier 3 --pretty
92
+ ```json
93
+ { "side": "long", "symbol": "JBTC", "margin": 60, "ppo": true, "ppo_expire": "8h", "ppo_category": "OTM", "ppo_tier": 3 }
106
94
  ```
107
95
 
108
96
  ---
109
97
 
110
- ## 2. Add PPO Protection (`jv order protect`)
98
+ ## 2. Add PPO Protection — `protect_order`
111
99
 
112
100
  Add hedge option protection to an **existing position** without changing position size.
113
101
 
114
- ### Syntax
115
-
116
- ```
117
- jv order protect --order-id <id> --symbol <symbol> [options]
118
- ```
119
-
120
- ### Options
102
+ ### Parameters
121
103
 
122
- | Option | Required | Default | Description |
123
- |--------|----------|---------|-------------|
124
- | `--order-id <id>` | Yes | — | Existing perps order ID |
125
- | `--symbol <symbol>` | Yes | — | Asset symbol (e.g., `JBTC`) |
126
- | `--ppo-expire <duration>` | No | `30m` | Option expiry: `30m` or `8h` |
127
- | `--ppo-category <ATM\|OTM>` | No | `ATM` | Option category |
128
- | `--ppo-tier <1-5>` | No | — | OTM strike offset tier (required if OTM) |
129
- | `--network <name>` | No | `jaspervault` | Network name |
130
- | `--ttl <seconds>` | No | `3600` | Signature TTL in seconds |
131
- | `--pretty` | No | — | Pretty-print JSON output |
104
+ | Parameter | Required | Default | Description |
105
+ |-----------|----------|---------|-------------|
106
+ | `order_id` | Yes | — | Existing perps order ID |
107
+ | `symbol` | Yes | — | Asset symbol (e.g., `JBTC`) |
108
+ | `ppo_expire` | No | `30m` | Option expiry: `30m` or `8h` |
109
+ | `ppo_category` | No | `ATM` | Option category: `ATM` or `OTM` |
110
+ | `ppo_tier` | No | — | OTM strike offset tier 1-5 (required if OTM) |
132
111
 
133
- ### Output
112
+ ### Response
134
113
 
135
- The command auto-waits up to 60s for the on-chain result via SSE:
114
+ The tool auto-waits up to 60s for the on-chain result:
136
115
  ```json
137
- {"jobId":"OPTION_ORDER_xxx","status":"completed","transactionHash":"0x..."}
116
+ {
117
+ "jobId": "OPTION_ORDER_xxx",
118
+ "status": "completed",
119
+ "transactionHash": "0x..."
120
+ }
138
121
  ```
139
122
 
140
123
  ### Important
141
124
 
142
- - Use `jv order protect` to add hedge to an **existing** position.
143
- - Do NOT use `jv order create --ppo` for this — that adds position size.
144
- - The CLI auto-detects position side (LONG/SHORT) from the order and selects the correct hedge type (PUT for LONG, CALL for SHORT).
125
+ - Use `protect_order` to add hedge to an **existing** position.
126
+ - Don't use `create_order` with `ppo: true` for this — that adds position size.
127
+ - The tool auto-detects position side (LONG/SHORT) and selects the correct hedge type.
145
128
 
146
129
  ---
147
130
 
148
- ## 3. Take-Profit (`jv tp set`)
131
+ ## 3. Take-Profit — `set_take_profit`
149
132
 
150
133
  Set a take-profit limit order for an existing position.
151
134
 
152
- ### Syntax
135
+ ### Parameters
153
136
 
154
- ```
155
- jv tp set --order-id <id> --price <usdc> --symbol <symbol> [options]
156
- ```
157
-
158
- ### Options
159
-
160
- | Option | Required | Default | Description |
161
- |--------|----------|---------|-------------|
162
- | `--order-id <id>` | Yes | — | Existing order ID (position to close) |
163
- | `--price <usdc>` | Yes | — | Target price in USDC |
164
- | `--symbol <symbol>` | Yes | — | Asset symbol (e.g., `JBTC`) |
165
- | `--side <long\|short>` | No | `long` | Position side being closed |
166
- | `--ppo` | No | — | Enable PPO hedge on the TP order |
167
- | `--ppo-expire <duration>` | No | `30m` | PPO expiry: `30m` or `8h` |
168
- | `--ppo-category <ATM\|OTM>` | No | `ATM` | PPO option category |
169
- | `--ppo-tier <1-5>` | No | — | OTM strike offset tier |
170
- | `--network <name>` | No | `jaspervault` | Network name |
171
- | `--ttl <seconds>` | No | `86400` | Order TTL in seconds (default: 24h) |
172
- | `--pretty` | No | — | Pretty-print JSON output |
173
-
174
- ### Output
175
-
176
- ```json
177
- {"success":true,"orderType":"limit","limitOrderId":"0x..."}
178
- ```
137
+ | Parameter | Required | Default | Description |
138
+ |-----------|----------|---------|-------------|
139
+ | `order_id` | Yes | — | Existing order ID |
140
+ | `price` | Yes | — | Target price in USDC |
141
+ | `symbol` | Yes | — | Asset symbol |
142
+ | `side` | No | `long` | Position side being closed |
143
+ | `ppo` | No | — | Enable PPO hedge on the TP order |
144
+ | `ppo_expire` | No | `30m` | PPO expiry |
145
+ | `ppo_category` | No | `ATM` | PPO category |
146
+ | `ppo_tier` | No | — | OTM tier |
147
+ | `ttl` | No | `86400` | Order TTL (default: 24h) |
179
148
 
180
149
  ### Example
181
150
 
182
- ```bash
183
- # Set TP at $75,000 for a long position
184
- jv tp set --order-id 123 --price 75000 --symbol JBTC --pretty
185
-
186
- # Set TP for a short position
187
- jv tp set --order-id 456 --price 60000 --symbol JBTC --side short --pretty
151
+ Set TP at $75,000 for a long position:
152
+ ```json
153
+ { "order_id": "123", "price": 75000, "symbol": "JBTC" }
188
154
  ```
189
155
 
190
156
  ---
191
157
 
192
- ## 4. Stop-Loss (`jv sl set`)
193
-
194
- Set a stop-loss limit order for an existing position. Same options as `jv tp set`.
158
+ ## 4. Stop-Loss — `set_stop_loss`
195
159
 
196
- ### Syntax
197
-
198
- ```
199
- jv sl set --order-id <id> --price <usdc> --symbol <symbol> [options]
200
- ```
201
-
202
- Options are identical to `jv tp set` (see above).
160
+ Same parameters as `set_take_profit`. Set a stop-loss limit order for an existing position.
203
161
 
204
162
  ### Example
205
163
 
206
- ```bash
207
- # Set SL at $65,000 for a long position
208
- jv sl set --order-id 123 --price 65000 --symbol JBTC --pretty
209
-
210
- # Set SL for a short position
211
- jv sl set --order-id 456 --price 80000 --symbol JBTC --side short --pretty
164
+ Set SL at $65,000 for a long position:
165
+ ```json
166
+ { "order_id": "123", "price": 65000, "symbol": "JBTC" }
212
167
  ```
213
168
 
214
169
  ---
215
170
 
216
171
  ## 5. PPO (Perpetual Put Option) Details
217
172
 
218
- PPO provides hedge protection for positions. Key concepts:
219
-
220
173
  ### Option Categories
221
174
 
222
- | Category | Description | `--ppo-tier` |
223
- |----------|-------------|--------------|
175
+ | Category | Description | `ppo_tier` |
176
+ |----------|-------------|------------|
224
177
  | `ATM` (default) | At-the-money — strike = current price | Not needed |
225
178
  | `OTM` | Out-of-the-money — strike offset from current price | Required (1-5) |
226
179
 
227
180
  ### OTM Tiers
228
181
 
229
- | Tier | Strike Offset | Ratio |
230
- |------|---------------|-------|
231
- | 1 | 0.1% | 0.001 |
232
- | 2 | 0.2% | 0.002 |
233
- | 3 | 0.3% | 0.003 |
234
- | 4 | 0.4% | 0.004 |
235
- | 5 | 0.5% | 0.005 |
182
+ | Tier | Strike Offset |
183
+ |------|---------------|
184
+ | 1 | 0.1% |
185
+ | 2 | 0.2% |
186
+ | 3 | 0.3% |
187
+ | 4 | 0.4% |
188
+ | 5 | 0.5% |
236
189
 
237
190
  ### Expiry Options
238
191
 
239
- | Duration | Seconds | Flag |
240
- |----------|---------|------|
241
- | 30 minutes (default) | 1800 | `--ppo-expire 30m` |
242
- | 8 hours | 28800 | `--ppo-expire 8h` |
192
+ | Duration | Flag |
193
+ |----------|------|
194
+ | 30 minutes (default) | `ppo_expire: "30m"` |
195
+ | 8 hours | `ppo_expire: "8h"` |
243
196
 
244
197
  ### Hedge Type (auto-selected)
245
198
 
@@ -248,27 +201,24 @@ PPO provides hedge protection for positions. Key concepts:
248
201
 
249
202
  ### Intent Mapping
250
203
 
251
- | User Says | Action | Command |
252
- |-----------|--------|---------|
253
- | "加保护" / "add protection" to existing | `jv order protect` | `jv order protect --order-id <id> --symbol JBTC` |
254
- | "开仓 + 保护" / "open with protection" | `jv order create --ppo` | `jv order create --side long -m 60 --symbol JBTC --ppo` |
255
- | "加仓 + 保护" / "add size with protection" | `jv order create --ppo` (same side) | `jv order create --side long -m 50 --symbol JBTC --ppo` |
256
- | "8小时" / "8 hour" | Add `--ppo-expire 8h` | |
257
- | "OTM" / "价外" | Add `--ppo-category OTM`, then ask for tier | |
258
- | "ATM" / "平价" or nothing | Default ATM, 30 min | |
259
- | "取消PPO" / "cancel PPO" / "remove hedge" | Order WITHOUT `--ppo` | See below |
260
-
261
- ### PPO Cancellation (IMPORTANT)
262
-
263
- 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**.
264
-
265
- | User Request | Correct Action | Command |
266
- |--------------|---------------|---------|
267
- | "减仓 + 取消PPO" | Single reduce order without `--ppo` | `jv order create --side <opposite> -m <amount> --symbol JBTC` |
268
- | "加仓 + 取消PPO" | Single add-size order without `--ppo` | `jv order create --side <same> -m <amount> --symbol JBTC` |
269
- | "平仓" (full close) | Close order without `--ppo` | `jv order create --side <opposite> -m <full_margin> --symbol JBTC` |
270
- | "减仓 + 保留PPO" | Reduce order WITH `--ppo` | `jv order create --side <opposite> -m <amount> --symbol JBTC --ppo` |
271
-
272
- **NEVER do this:**
273
- - Do NOT try to cancel PPO as a separate step. There is no "cancel PPO" command.
274
- - Do NOT send two orders when one suffices. "减仓 + 取消PPO" = ONE order without `--ppo`.
204
+ | User Says | Tool | Parameters |
205
+ |-----------|------|------------|
206
+ | "add protection" to existing | `protect_order` | `{ order_id, symbol }` |
207
+ | "open with protection" | `create_order` | `{ side, symbol, margin, ppo: true }` |
208
+ | "add size with protection" | `create_order` (same side) | `{ side, symbol, margin, ppo: true }` |
209
+ | "8 hours" | any PPO tool | add `ppo_expire: "8h"` |
210
+ | "OTM" | any PPO tool | add `ppo_category: "OTM"`, then need `ppo_tier` |
211
+ | "cancel PPO" / "remove hedge" | `create_order` | without `ppo` — see below |
212
+
213
+ ### PPO Cancellation
214
+
215
+ The smart contract **automatically cancels** existing PPO when you execute any position operation without `ppo: true`. There is no separate "cancel PPO" tool.
216
+
217
+ | User Request | Action | Parameters |
218
+ |-------------|--------|------------|
219
+ | "reduce + cancel PPO" | Single reduce order without `ppo` | `{ side: <opposite>, symbol, margin }` |
220
+ | "add size + cancel PPO" | Single add-size order without `ppo` | `{ side: <same>, symbol, margin }` |
221
+ | "close position" | Close order without `ppo` | `{ side: <opposite>, symbol, margin: <full> }` |
222
+ | "reduce + keep PPO" | Reduce order WITH `ppo` | `{ side: <opposite>, symbol, margin, ppo: true }` |
223
+
224
+ Never try to cancel PPO separately — there is no such tool. One order handles everything.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "jaspervault_cli",
3
- "version": "1.0.28",
3
+ "version": "1.0.29",
4
4
  "description": "JasperVault CLI for interacting with the JasperVault Manager API",
5
5
  "type": "module",
6
6
  "bin": {