jaspervault_cli 1.0.11 → 1.0.14
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.
|
@@ -35,6 +35,23 @@ Interact with JasperVault's perpetual contract platform. You can create market/l
|
|
|
35
35
|
- **First-time setup**: use \`jv vault init-wc\` to initialize via WalletConnect (scan QR on phone, sign delegation — no private key needed)
|
|
36
36
|
- API URL defaults to the JasperVault trading endpoint; no environment variables needed for normal use
|
|
37
37
|
|
|
38
|
+
## Activation Behavior
|
|
39
|
+
|
|
40
|
+
When this skill is activated (first message from the user, OR any trading intent such as open position, check portfolio, deposit, etc.):
|
|
41
|
+
|
|
42
|
+
1. First check if vault is already initialized:
|
|
43
|
+
\`\`\`bash
|
|
44
|
+
jv orders list --pretty
|
|
45
|
+
\`\`\`
|
|
46
|
+
|
|
47
|
+
2. If the command fails with "delegation key not found", "vault not initialized", "no profile", or similar error (exit code 1):
|
|
48
|
+
- Tell the user: "Your vault is not initialized yet. Let me start the setup via WalletConnect — no private key needed."
|
|
49
|
+
- Immediately run \`jv vault init-wc --network jaspervault --timeout 120\` and follow the QR code display instructions in the Setup Flow section below.
|
|
50
|
+
|
|
51
|
+
3. If the command succeeds → vault is ready. Proceed with the user's request.
|
|
52
|
+
|
|
53
|
+
IMPORTANT: Always use WalletConnect initialization (\`jv vault init-wc\`). Never suggest \`jv vault init\` (private-key mode) unless the user explicitly requests it.
|
|
54
|
+
|
|
38
55
|
## Setup Flow (First Time — WalletConnect)
|
|
39
56
|
|
|
40
57
|
\`\`\`bash
|
|
@@ -45,32 +62,121 @@ jv vault init-wc --network jaspervault --timeout 120
|
|
|
45
62
|
CRITICAL EXECUTION NOTE: This command runs for up to 2 minutes. Do NOT interrupt or kill the process after the first JSON line. Wait for the process to exit naturally (second JSON output = success or failure).
|
|
46
63
|
|
|
47
64
|
The command outputs two JSON lines:
|
|
48
|
-
|
|
65
|
+
|
|
66
|
+
1. \`{"status":"awaiting_connection", "uri":"wc:...", "qrCodeUrl":"https://api.qrserver.com/v1/create-qr-code/?size=400x400&data=wc%3A...", ...}\`
|
|
67
|
+
|
|
68
|
+
Extract the \`qrCodeUrl\` field from the JSON. It will be a URL starting with \`https://api.qrserver.com/v1/create-qr-code/\`. You MUST send it as a markdown image so it renders as a scannable QR code:
|
|
69
|
+
|
|
70
|
+
\`\`\`
|
|
71
|
+
|
|
72
|
+
\`\`\`
|
|
73
|
+
|
|
74
|
+
Replace the URL above with the actual \`qrCodeUrl\` from the JSON output. Also provide the \`uri\` as a fallback:
|
|
75
|
+
|
|
76
|
+
> Or open your wallet app → WalletConnect → paste this URI: \`wc:...\`
|
|
77
|
+
|
|
78
|
+
CRITICAL: MUST use markdown image syntax \`\`. NEVER post the URL as plain text. NEVER print \`qrCodeText\`. NEVER generate your own QR code. The image will not appear if you only post the raw URL without the \`![...]()\` wrapper.
|
|
79
|
+
|
|
49
80
|
2. \`{"success":true, "message":"Vault initialized successfully", ...}\` — Init complete. The delegation wallet is saved to \`~/.jaspervault/keys.json\` and vault addresses to \`~/.jaspervault/profile.json\`. Subsequent commands use these automatically — no wallet interaction needed.
|
|
50
81
|
|
|
51
82
|
Do NOT ask the user to set \`PRIVATE_KEY\`. Do NOT suggest \`jv vault init\` unless the user explicitly requests private-key mode.
|
|
52
83
|
|
|
84
|
+
## Key Concepts (MUST READ before any trading operation)
|
|
85
|
+
|
|
86
|
+
Understanding these relationships is CRITICAL for passing correct parameters:
|
|
87
|
+
|
|
88
|
+
\`\`\`
|
|
89
|
+
--margin-amount = NOTIONAL VALUE (NOT actual margin/collateral!)
|
|
90
|
+
\`\`\`
|
|
91
|
+
|
|
92
|
+
**Formulas:**
|
|
93
|
+
|
|
94
|
+
| Concept | Formula | Example |
|
|
95
|
+
|---------|---------|---------|
|
|
96
|
+
| Notional value | \`margin × leverage\` | 60 USDC × 50x = $3,000 |
|
|
97
|
+
| Actual margin (collateral) | \`notional / leverage\` | $3,000 / 50 = 60 USDC |
|
|
98
|
+
| Position size | \`notional / current_price\` | $3,000 / $70,000 = 0.0428 JBTC |
|
|
99
|
+
|
|
100
|
+
**How \`--margin-amount\` works internally:**
|
|
101
|
+
|
|
102
|
+
The \`--margin-amount\` parameter takes the **notional value** (total leveraged position value in USDC). The CLI internally divides by leverage to get the actual margin:
|
|
103
|
+
|
|
104
|
+
- User passes: \`--margin-amount 3000 --leverage 50\`
|
|
105
|
+
- CLI calculates: actual margin = 3000 / 50 = 60 USDC (collateral locked)
|
|
106
|
+
- Position created: $3,000 notional, 60 USDC collateral, ~0.0428 JBTC size
|
|
107
|
+
|
|
108
|
+
**Translating user intent to \`--margin-amount\` (three scenarios):**
|
|
109
|
+
|
|
110
|
+
| User says | Calculation | Pass to CLI |
|
|
111
|
+
|-----------|-------------|-------------|
|
|
112
|
+
| "long 0.1 BTC at 50x" | notional = 0.1 × current_price | \`--margin-amount <notional>\` |
|
|
113
|
+
| "long with $60 USDC margin at 50x" | notional = 60 × 50 = 3000 | \`--margin-amount 3000\` |
|
|
114
|
+
| "open a $3,000 position at 50x" | already notional | \`--margin-amount 3000\` |
|
|
115
|
+
|
|
116
|
+
CRITICAL: When the user specifies an asset amount (e.g. "0.1 BTC"), you MUST first estimate the current price, then compute \`notional = size × price\` before passing \`--margin-amount\`. Do NOT pass the asset quantity directly.
|
|
117
|
+
|
|
118
|
+
**How to read \`jv orders list\` output:**
|
|
119
|
+
|
|
120
|
+
| Field | What it means |
|
|
121
|
+
|-------|---------------|
|
|
122
|
+
| \`margin\` | Actual collateral deposited (e.g. 60 USDC) — this is NOT the notional value |
|
|
123
|
+
| \`size\` | Position size in underlying asset (e.g. 0.0428 JBTC) |
|
|
124
|
+
| \`leverage\` | Leverage multiplier (e.g. 50) |
|
|
125
|
+
| \`entryPriceUsd\` | Entry price when position was opened |
|
|
126
|
+
|
|
127
|
+
To calculate notional from output: \`notional = margin × leverage\` (or \`size × current_price\`)
|
|
128
|
+
|
|
53
129
|
## Intent Mapping
|
|
54
130
|
|
|
55
|
-
### Creating Orders
|
|
131
|
+
### Creating Orders (Open New Position)
|
|
56
132
|
|
|
57
133
|
When the user wants to **open a position**, **place a market order**, or **place a limit order**:
|
|
58
134
|
|
|
59
135
|
\`\`\`bash
|
|
60
|
-
# Market order
|
|
61
|
-
jv order create --side long --symbol JBTC --margin-amount
|
|
136
|
+
# Market order: Long JBTC, $3000 notional at 50x (= 60 USDC margin)
|
|
137
|
+
jv order create --side long --symbol JBTC --margin-amount 3000 --leverage 50 --network jaspervault
|
|
62
138
|
|
|
63
|
-
# Market order (
|
|
64
|
-
jv order create --side short --symbol JBTC --margin-amount
|
|
139
|
+
# Market order: Short JBTC, $5000 notional at 50x (= 100 USDC margin)
|
|
140
|
+
jv order create --side short --symbol JBTC --margin-amount 5000 --leverage 50 --network jaspervault
|
|
65
141
|
|
|
66
|
-
# Limit order
|
|
67
|
-
jv order create --side long --symbol JBTC --margin-amount
|
|
142
|
+
# Limit order: add --limit-price
|
|
143
|
+
jv order create --side long --symbol JBTC --margin-amount 3000 --leverage 50 --limit-price 65000 --network jaspervault
|
|
68
144
|
\`\`\`
|
|
69
145
|
|
|
70
146
|
The CLI signs the order internally using the delegation wallet. No pre-signed payload required.
|
|
71
147
|
|
|
72
148
|
On success, a market order returns \`jobId\`; a limit order returns \`limitOrderId\`.
|
|
73
149
|
|
|
150
|
+
### Reducing / Partially Closing a Position
|
|
151
|
+
|
|
152
|
+
To reduce a position, create an **opposite-side order** with the notional value you want to close. The system automatically detects existing positions and performs a partial close.
|
|
153
|
+
|
|
154
|
+
**Step-by-step for reducing a position:**
|
|
155
|
+
|
|
156
|
+
1. Query current position: \`jv orders list --pretty\`
|
|
157
|
+
2. Calculate notional to close:
|
|
158
|
+
- From output fields: \`notional = margin × leverage\` (or \`size × current_price\`)
|
|
159
|
+
- To close half: \`close_notional = notional / 2\`
|
|
160
|
+
3. Create opposite-side order with that notional value
|
|
161
|
+
|
|
162
|
+
**Example: Reduce a LONG position by half**
|
|
163
|
+
|
|
164
|
+
Current position from \`jv orders list\`:
|
|
165
|
+
- margin: 60 USDC, leverage: 50, size: 0.0428 JBTC
|
|
166
|
+
- notional = 60 × 50 = $3,000
|
|
167
|
+
|
|
168
|
+
To close half ($1,500 notional):
|
|
169
|
+
\`\`\`bash
|
|
170
|
+
jv order create --side short --symbol JBTC --margin-amount 1500 --leverage 50 --network jaspervault
|
|
171
|
+
\`\`\`
|
|
172
|
+
|
|
173
|
+
**Example: Close entire position ($3,000 notional):**
|
|
174
|
+
\`\`\`bash
|
|
175
|
+
jv order create --side short --symbol JBTC --margin-amount 3000 --leverage 50 --network jaspervault
|
|
176
|
+
\`\`\`
|
|
177
|
+
|
|
178
|
+
IMPORTANT: The \`--margin-amount\` for reduction = notional value to close, NOT the margin.
|
|
179
|
+
|
|
74
180
|
### Setting Take-Profit
|
|
75
181
|
|
|
76
182
|
When the user wants to **set take-profit**, **set TP**, or **protect profits**:
|
|
@@ -166,23 +272,38 @@ Possible statuses: PENDING, TRIGGERED, EXECUTING, COMPLETED, FAILED, EXPIRED, CA
|
|
|
166
272
|
|
|
167
273
|
All commands output JSON to stdout. Extract key fields to compose user-friendly responses.
|
|
168
274
|
|
|
169
|
-
|
|
275
|
+
### Market Order Output (IMPORTANT — two JSON lines)
|
|
276
|
+
|
|
277
|
+
\`jv order create\` for market orders prints **two JSON lines sequentially**:
|
|
278
|
+
|
|
279
|
+
**Line 1 — Order submitted:**
|
|
170
280
|
\`\`\`json
|
|
171
|
-
{"success":true,"orderType":"market","jobId":"MARKET_ORDER_xxx"}
|
|
281
|
+
{"success":true,"orderType":"market","jobId":"MARKET_ORDER_xxx","statusUrl":"/api/job/status/...","streamUrl":"/api/job/stream/..."}
|
|
172
282
|
\`\`\`
|
|
173
|
-
Tell the user: "Market order submitted. Job ID: {jobId}. Checking status..."
|
|
174
283
|
|
|
175
|
-
**
|
|
284
|
+
**Line 2 — Execution result (auto-waits up to 60s):**
|
|
176
285
|
\`\`\`json
|
|
177
|
-
{"
|
|
286
|
+
{"jobId":"MARKET_ORDER_xxx","status":"completed","transactionHash":"0x..."}
|
|
178
287
|
\`\`\`
|
|
179
|
-
Tell the user: "Limit order placed. ID: {limitOrderId}."
|
|
180
288
|
|
|
181
|
-
**
|
|
289
|
+
**How to determine success:**
|
|
290
|
+
|
|
291
|
+
- If \`status === "completed"\` → the order is DONE. It succeeded on-chain.
|
|
292
|
+
- If \`status === "failed"\` → the order failed. Report the error.
|
|
293
|
+
- If \`status === "timeout"\` → timed out waiting; use \`jv job status <jobId>\` to check later.
|
|
294
|
+
|
|
295
|
+
**CRITICAL RULES after order execution:**
|
|
296
|
+
|
|
297
|
+
1. **If \`status\` is \`"completed"\`, the order IS executed. Do NOT retry or place another order.**
|
|
298
|
+
2. The \`operation\` field (if present) contains raw on-chain data in wei format — do NOT try to interpret quantities or amounts from it. Values like \`10029000\` are NOT human-readable USDC or BTC amounts.
|
|
299
|
+
3. **To verify the actual position after a successful order**, always run \`jv orders list --pretty\` and read the human-readable \`margin\`, \`size\`, \`leverage\` fields. Use \`notional = margin × leverage\` to show the user their position value.
|
|
300
|
+
4. Report to the user: "Order executed successfully. Tx: {transactionHash}. Let me check your updated position..." then run \`jv orders list --pretty\`.
|
|
301
|
+
|
|
302
|
+
**Limit order created:**
|
|
182
303
|
\`\`\`json
|
|
183
|
-
{"
|
|
304
|
+
{"success":true,"orderType":"limit","limitOrderId":"0x..."}
|
|
184
305
|
\`\`\`
|
|
185
|
-
Tell the user: "
|
|
306
|
+
Tell the user: "Limit order placed. ID: {limitOrderId}."
|
|
186
307
|
|
|
187
308
|
## Error Handling
|
|
188
309
|
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"skill-body.js","sourceRoot":"","sources":["../../../src/templates/skill-body.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CACzC,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,uBAAuB,CAAC,EAAE,OAAO,CAAC,CACzC,CAAC;AAEzB,sEAAsE;AACtE,MAAM,CAAC,MAAM,MAAM,GAAG;;;;;;;;;;;;;;wBAcE,WAAW;;CAElC,CAAC,IAAI,EAAE,CAAC;AAET,2EAA2E;AAC3E,MAAM,kBAAkB,GAAG
|
|
1
|
+
{"version":3,"file":"skill-body.js","sourceRoot":"","sources":["../../../src/templates/skill-body.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CACzC,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,uBAAuB,CAAC,EAAE,OAAO,CAAC,CACzC,CAAC;AAEzB,sEAAsE;AACtE,MAAM,CAAC,MAAM,MAAM,GAAG;;;;;;;;;;;;;;wBAcE,WAAW;;CAElC,CAAC,IAAI,EAAE,CAAC;AAET,2EAA2E;AAC3E,MAAM,kBAAkB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqS1B,CAAC,IAAI,EAAE,CAAC;AAET,SAAS,sBAAsB;IAC7B,OAAO;;;;;;;;;;;CAWR,CAAC;AACF,CAAC;AAED,SAAS,oBAAoB;IAC3B,OAAO;;;;CAIR,CAAC;AACF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB;IAChD,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,UAAU;YACb,OAAO,sBAAsB,EAAE,GAAG,mCAAmC,GAAG,kBAAkB,CAAC;QAC7F,KAAK,QAAQ;YACX,OAAO,oBAAoB,EAAE,GAAG,mCAAmC,GAAG,kBAAkB,CAAC;QAC3F,KAAK,QAAQ;YACX,OAAO,wBAAwB,GAAG,kBAAkB,CAAC;QACvD;YACE,MAAM,IAAI,KAAK,CAAC,qBAAqB,QAAQ,EAAE,CAAC,CAAC;IACrD,CAAC;AACH,CAAC"}
|