jaspervault_cli 1.0.11 → 1.0.13
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.
|
@@ -45,32 +45,107 @@ jv vault init-wc --network jaspervault --timeout 120
|
|
|
45
45
|
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
46
|
|
|
47
47
|
The command outputs two JSON lines:
|
|
48
|
-
1. \`{"status":"awaiting_connection", "uri":"wc:...", "qrCodeUrl":"https://api.qrserver.com/...", ...}\` —
|
|
48
|
+
1. \`{"status":"awaiting_connection", "uri":"wc:...", "qrCodeUrl":"https://api.qrserver.com/...", ...}\` — Display the QR code as a markdown image: \`\`. Do NOT print \`qrCodeText\` — the text-art QR code breaks alignment in markdown rendering and cannot be scanned. Also provide the \`uri\` as a fallback for manual paste in the wallet app.
|
|
49
49
|
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
50
|
|
|
51
51
|
Do NOT ask the user to set \`PRIVATE_KEY\`. Do NOT suggest \`jv vault init\` unless the user explicitly requests private-key mode.
|
|
52
52
|
|
|
53
|
+
## Key Concepts (MUST READ before any trading operation)
|
|
54
|
+
|
|
55
|
+
Understanding these relationships is CRITICAL for passing correct parameters:
|
|
56
|
+
|
|
57
|
+
\`\`\`
|
|
58
|
+
--margin-amount = NOTIONAL VALUE (NOT actual margin/collateral!)
|
|
59
|
+
\`\`\`
|
|
60
|
+
|
|
61
|
+
**Formulas:**
|
|
62
|
+
|
|
63
|
+
| Concept | Formula | Example |
|
|
64
|
+
|---------|---------|---------|
|
|
65
|
+
| Notional value | \`margin × leverage\` | 60 USDC × 50x = $3,000 |
|
|
66
|
+
| Actual margin (collateral) | \`notional / leverage\` | $3,000 / 50 = 60 USDC |
|
|
67
|
+
| Position size | \`notional / current_price\` | $3,000 / $70,000 = 0.0428 JBTC |
|
|
68
|
+
|
|
69
|
+
**How \`--margin-amount\` works internally:**
|
|
70
|
+
|
|
71
|
+
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:
|
|
72
|
+
|
|
73
|
+
- User passes: \`--margin-amount 3000 --leverage 50\`
|
|
74
|
+
- CLI calculates: actual margin = 3000 / 50 = 60 USDC (collateral locked)
|
|
75
|
+
- Position created: $3,000 notional, 60 USDC collateral, ~0.0428 JBTC size
|
|
76
|
+
|
|
77
|
+
**Translating user intent to \`--margin-amount\` (three scenarios):**
|
|
78
|
+
|
|
79
|
+
| User says | Calculation | Pass to CLI |
|
|
80
|
+
|-----------|-------------|-------------|
|
|
81
|
+
| "long 0.1 BTC at 50x" | notional = 0.1 × current_price | \`--margin-amount <notional>\` |
|
|
82
|
+
| "long with $60 USDC margin at 50x" | notional = 60 × 50 = 3000 | \`--margin-amount 3000\` |
|
|
83
|
+
| "open a $3,000 position at 50x" | already notional | \`--margin-amount 3000\` |
|
|
84
|
+
|
|
85
|
+
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.
|
|
86
|
+
|
|
87
|
+
**How to read \`jv orders list\` output:**
|
|
88
|
+
|
|
89
|
+
| Field | What it means |
|
|
90
|
+
|-------|---------------|
|
|
91
|
+
| \`margin\` | Actual collateral deposited (e.g. 60 USDC) — this is NOT the notional value |
|
|
92
|
+
| \`size\` | Position size in underlying asset (e.g. 0.0428 JBTC) |
|
|
93
|
+
| \`leverage\` | Leverage multiplier (e.g. 50) |
|
|
94
|
+
| \`entryPriceUsd\` | Entry price when position was opened |
|
|
95
|
+
|
|
96
|
+
To calculate notional from output: \`notional = margin × leverage\` (or \`size × current_price\`)
|
|
97
|
+
|
|
53
98
|
## Intent Mapping
|
|
54
99
|
|
|
55
|
-
### Creating Orders
|
|
100
|
+
### Creating Orders (Open New Position)
|
|
56
101
|
|
|
57
102
|
When the user wants to **open a position**, **place a market order**, or **place a limit order**:
|
|
58
103
|
|
|
59
104
|
\`\`\`bash
|
|
60
|
-
# Market order
|
|
61
|
-
jv order create --side long --symbol JBTC --margin-amount
|
|
105
|
+
# Market order: Long JBTC, $3000 notional at 50x (= 60 USDC margin)
|
|
106
|
+
jv order create --side long --symbol JBTC --margin-amount 3000 --leverage 50 --network jaspervault
|
|
62
107
|
|
|
63
|
-
# Market order (
|
|
64
|
-
jv order create --side short --symbol JBTC --margin-amount
|
|
108
|
+
# Market order: Short JBTC, $5000 notional at 50x (= 100 USDC margin)
|
|
109
|
+
jv order create --side short --symbol JBTC --margin-amount 5000 --leverage 50 --network jaspervault
|
|
65
110
|
|
|
66
|
-
# Limit order
|
|
67
|
-
jv order create --side long --symbol JBTC --margin-amount
|
|
111
|
+
# Limit order: add --limit-price
|
|
112
|
+
jv order create --side long --symbol JBTC --margin-amount 3000 --leverage 50 --limit-price 65000 --network jaspervault
|
|
68
113
|
\`\`\`
|
|
69
114
|
|
|
70
115
|
The CLI signs the order internally using the delegation wallet. No pre-signed payload required.
|
|
71
116
|
|
|
72
117
|
On success, a market order returns \`jobId\`; a limit order returns \`limitOrderId\`.
|
|
73
118
|
|
|
119
|
+
### Reducing / Partially Closing a Position
|
|
120
|
+
|
|
121
|
+
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.
|
|
122
|
+
|
|
123
|
+
**Step-by-step for reducing a position:**
|
|
124
|
+
|
|
125
|
+
1. Query current position: \`jv orders list --pretty\`
|
|
126
|
+
2. Calculate notional to close:
|
|
127
|
+
- From output fields: \`notional = margin × leverage\` (or \`size × current_price\`)
|
|
128
|
+
- To close half: \`close_notional = notional / 2\`
|
|
129
|
+
3. Create opposite-side order with that notional value
|
|
130
|
+
|
|
131
|
+
**Example: Reduce a LONG position by half**
|
|
132
|
+
|
|
133
|
+
Current position from \`jv orders list\`:
|
|
134
|
+
- margin: 60 USDC, leverage: 50, size: 0.0428 JBTC
|
|
135
|
+
- notional = 60 × 50 = $3,000
|
|
136
|
+
|
|
137
|
+
To close half ($1,500 notional):
|
|
138
|
+
\`\`\`bash
|
|
139
|
+
jv order create --side short --symbol JBTC --margin-amount 1500 --leverage 50 --network jaspervault
|
|
140
|
+
\`\`\`
|
|
141
|
+
|
|
142
|
+
**Example: Close entire position ($3,000 notional):**
|
|
143
|
+
\`\`\`bash
|
|
144
|
+
jv order create --side short --symbol JBTC --margin-amount 3000 --leverage 50 --network jaspervault
|
|
145
|
+
\`\`\`
|
|
146
|
+
|
|
147
|
+
IMPORTANT: The \`--margin-amount\` for reduction = notional value to close, NOT the margin.
|
|
148
|
+
|
|
74
149
|
### Setting Take-Profit
|
|
75
150
|
|
|
76
151
|
When the user wants to **set take-profit**, **set TP**, or **protect profits**:
|
|
@@ -166,23 +241,38 @@ Possible statuses: PENDING, TRIGGERED, EXECUTING, COMPLETED, FAILED, EXPIRED, CA
|
|
|
166
241
|
|
|
167
242
|
All commands output JSON to stdout. Extract key fields to compose user-friendly responses.
|
|
168
243
|
|
|
169
|
-
|
|
244
|
+
### Market Order Output (IMPORTANT — two JSON lines)
|
|
245
|
+
|
|
246
|
+
\`jv order create\` for market orders prints **two JSON lines sequentially**:
|
|
247
|
+
|
|
248
|
+
**Line 1 — Order submitted:**
|
|
170
249
|
\`\`\`json
|
|
171
|
-
{"success":true,"orderType":"market","jobId":"MARKET_ORDER_xxx"}
|
|
250
|
+
{"success":true,"orderType":"market","jobId":"MARKET_ORDER_xxx","statusUrl":"/api/job/status/...","streamUrl":"/api/job/stream/..."}
|
|
172
251
|
\`\`\`
|
|
173
|
-
Tell the user: "Market order submitted. Job ID: {jobId}. Checking status..."
|
|
174
252
|
|
|
175
|
-
**
|
|
253
|
+
**Line 2 — Execution result (auto-waits up to 60s):**
|
|
176
254
|
\`\`\`json
|
|
177
|
-
{"
|
|
255
|
+
{"jobId":"MARKET_ORDER_xxx","status":"completed","transactionHash":"0x..."}
|
|
178
256
|
\`\`\`
|
|
179
|
-
Tell the user: "Limit order placed. ID: {limitOrderId}."
|
|
180
257
|
|
|
181
|
-
**
|
|
258
|
+
**How to determine success:**
|
|
259
|
+
|
|
260
|
+
- If \`status === "completed"\` → the order is DONE. It succeeded on-chain.
|
|
261
|
+
- If \`status === "failed"\` → the order failed. Report the error.
|
|
262
|
+
- If \`status === "timeout"\` → timed out waiting; use \`jv job status <jobId>\` to check later.
|
|
263
|
+
|
|
264
|
+
**CRITICAL RULES after order execution:**
|
|
265
|
+
|
|
266
|
+
1. **If \`status\` is \`"completed"\`, the order IS executed. Do NOT retry or place another order.**
|
|
267
|
+
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.
|
|
268
|
+
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.
|
|
269
|
+
4. Report to the user: "Order executed successfully. Tx: {transactionHash}. Let me check your updated position..." then run \`jv orders list --pretty\`.
|
|
270
|
+
|
|
271
|
+
**Limit order created:**
|
|
182
272
|
\`\`\`json
|
|
183
|
-
{"
|
|
273
|
+
{"success":true,"orderType":"limit","limitOrderId":"0x..."}
|
|
184
274
|
\`\`\`
|
|
185
|
-
Tell the user: "
|
|
275
|
+
Tell the user: "Limit order placed. ID: {limitOrderId}."
|
|
186
276
|
|
|
187
277
|
## Error Handling
|
|
188
278
|
|
|
@@ -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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsQ1B,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"}
|