jaspervault_cli 1.0.30 → 1.0.31
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.
package/README.md
CHANGED
|
@@ -1,135 +1,103 @@
|
|
|
1
1
|
# JasperVault CLI
|
|
2
2
|
|
|
3
|
-
Trade perpetuals on JasperVault through AI
|
|
3
|
+
Trade perpetuals on JasperVault through your AI assistant. Install the CLI, connect your AI platform, and start trading with natural language — no terminal commands needed.
|
|
4
4
|
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
## Quick Start
|
|
8
8
|
|
|
9
|
-
### 1. Install
|
|
9
|
+
### 1. Install
|
|
10
10
|
|
|
11
11
|
```bash
|
|
12
12
|
npm install -g jaspervault_cli
|
|
13
13
|
```
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
### 2. Connect to Your AI
|
|
16
16
|
|
|
17
17
|
```bash
|
|
18
|
-
jv --
|
|
18
|
+
jv install --ai claude # Claude Code
|
|
19
|
+
jv install --ai cursor # Cursor
|
|
20
|
+
jv install --ai openclaw # OpenClaw
|
|
19
21
|
```
|
|
20
22
|
|
|
21
|
-
|
|
23
|
+
This registers the JasperVault MCP server (or skill) so your AI assistant can trade on your behalf.
|
|
22
24
|
|
|
23
|
-
|
|
24
|
-
jv install --ai openclaw
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
This installs the trading skill/MCP configuration for your chosen platform. For OpenClaw it writes to `~/.openclaw/skills/jasper-vault-cli/SKILL.md`; for Cursor and Claude Code it configures the MCP server.
|
|
28
|
-
|
|
29
|
-
> To overwrite an existing installation, add `--force`:
|
|
30
|
-
> ```bash
|
|
31
|
-
> jv install --ai openclaw --force
|
|
32
|
-
> ```
|
|
25
|
+
> Add `--force` to overwrite an existing installation.
|
|
33
26
|
|
|
34
|
-
### 3.
|
|
27
|
+
### 3. Start Trading
|
|
35
28
|
|
|
36
|
-
|
|
29
|
+
Open your AI assistant and talk:
|
|
37
30
|
|
|
38
|
-
>
|
|
31
|
+
> "Open a long BTC position with 100 USDC"
|
|
39
32
|
|
|
40
|
-
|
|
33
|
+
That's it. The AI handles everything through MCP tools — wallet setup, order placement, position management.
|
|
41
34
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
```bash
|
|
45
|
-
jv vault setup --network jaspervault --pretty
|
|
46
|
-
```
|
|
35
|
+
---
|
|
47
36
|
|
|
48
|
-
|
|
37
|
+
## What You Can Do
|
|
49
38
|
|
|
50
|
-
Just
|
|
39
|
+
Just tell your AI assistant what you want:
|
|
51
40
|
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
41
|
+
| Say this | What happens |
|
|
42
|
+
|----------|-------------|
|
|
43
|
+
| "I want to start trading" | Sets up your wallet (one-time, browser signing) |
|
|
44
|
+
| "Open a long BTC position with 100 USDC" | Opens a market long on JBTC |
|
|
45
|
+
| "Go short ETH with 50 USDC at 3800" | Places a limit short on JETH |
|
|
46
|
+
| "Close my BTC position" | Queries your position, then closes it |
|
|
47
|
+
| "Set take-profit at 110000 for order 99" | Places a TP limit order |
|
|
48
|
+
| "Set stop-loss at 60000 for order 99" | Places a SL limit order |
|
|
49
|
+
| "Show my positions" | Lists all active positions |
|
|
50
|
+
| "What's the current BTC price?" | Fetches real-time price |
|
|
51
|
+
| "Deposit 500 USDC" | Opens browser to approve deposit |
|
|
52
|
+
| "Withdraw 100 USDC" | Opens browser to sign withdrawal |
|
|
53
|
+
| "Add PPO protection to order 42" | Adds hedge option to existing position |
|
|
55
54
|
|
|
56
55
|
---
|
|
57
56
|
|
|
58
|
-
##
|
|
59
|
-
|
|
60
|
-
```bash
|
|
61
|
-
jv install --ai openclaw # OpenClaw
|
|
62
|
-
jv install --ai cursor # Cursor (current project)
|
|
63
|
-
jv install --ai cursor --global # Cursor (user-level)
|
|
64
|
-
jv install --ai claude # Claude Code (current project)
|
|
65
|
-
jv install --ai claude --global # Claude Code (user-level)
|
|
66
|
-
jv install # All platforms (global)
|
|
67
|
-
```
|
|
68
|
-
|
|
69
|
-
Options:
|
|
70
|
-
- `--ai <platform>` — Target a specific platform (`openclaw`, `cursor`, `claude`)
|
|
71
|
-
- `--global` — Install to user home instead of current project (cursor/claude only)
|
|
72
|
-
- `--force` — Overwrite existing installation without prompting
|
|
57
|
+
## Platform Setup
|
|
73
58
|
|
|
74
|
-
|
|
59
|
+
| Platform | Command | What it does |
|
|
60
|
+
|----------|---------|-------------|
|
|
61
|
+
| Claude Code | `jv install --ai claude` | Configures MCP server (project-level) |
|
|
62
|
+
| Claude Code (global) | `jv install --ai claude --global` | Configures MCP server (user-level) |
|
|
63
|
+
| Cursor | `jv install --ai cursor` | Configures MCP server (project-level) |
|
|
64
|
+
| Cursor (global) | `jv install --ai cursor --global` | Configures MCP server (user-level) |
|
|
65
|
+
| OpenClaw | `jv install --ai openclaw` | Installs trading skill |
|
|
66
|
+
| All platforms | `jv install` | Installs to all platforms (global) |
|
|
75
67
|
|
|
76
68
|
---
|
|
77
69
|
|
|
78
70
|
## Configuration
|
|
79
71
|
|
|
80
|
-
All configuration is
|
|
72
|
+
All configuration is via environment variables. **No configuration is needed for most users** — the CLI connects to the JasperVault test environment by default.
|
|
81
73
|
|
|
82
74
|
| Variable | Required | Description | Default |
|
|
83
75
|
|----------|----------|-------------|---------|
|
|
84
76
|
| `JV_API_URL` | No | Trading API base URL | `https://trading-api-test.jaspervault.pro` |
|
|
85
77
|
| `JV_API_KEY` | No | Bearer token for API authentication | — |
|
|
86
78
|
| `JV_TIMEOUT` | No | Request timeout in ms | `30000` |
|
|
87
|
-
| `JV_DELEGATION_KEY` | No | Delegation wallet private key override
|
|
88
|
-
| `JV_BASE_RPC_URL` | No | Base chain RPC URL override
|
|
79
|
+
| `JV_DELEGATION_KEY` | No | Delegation wallet private key override | from `~/.jaspervault/keys.json` |
|
|
80
|
+
| `JV_BASE_RPC_URL` | No | Base chain RPC URL override | built-in |
|
|
89
81
|
| `JV_JASPERVAULT_RPC_URL` | No | JasperVault chain RPC URL override | built-in |
|
|
90
82
|
| `JV_SUBGRAPH_URL` | No | Subgraph endpoint override | built-in per network |
|
|
91
|
-
| `PRIVATE_KEY` | No | EOA wallet private key
|
|
83
|
+
| `PRIVATE_KEY` | No | EOA wallet private key (CI/automation only) | — |
|
|
92
84
|
|
|
93
|
-
###
|
|
85
|
+
### How Credentials Work
|
|
94
86
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
```bash
|
|
98
|
-
export JV_API_URL=https://your-api-endpoint.example.com
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
Then restart your terminal or run `source ~/.zshrc`.
|
|
102
|
-
|
|
103
|
-
### How Credentials Are Stored
|
|
104
|
-
|
|
105
|
-
After the first successful `jv vault init` or `jv vault setup`, the delegation wallet is saved to `~/.jaspervault/keys.json` and your vault profile to `~/.jaspervault/profile.json`. The CLI reads these automatically — no manual configuration needed for subsequent operations.
|
|
87
|
+
After the first wallet setup (triggered by your AI or manually via `jv vault setup`), the delegation wallet is saved to `~/.jaspervault/keys.json` and your vault profile to `~/.jaspervault/profile.json`. Everything is automatic after that.
|
|
106
88
|
|
|
107
89
|
---
|
|
108
90
|
|
|
109
|
-
##
|
|
110
|
-
|
|
111
|
-
To deposit tokens from Base to JasperVault, tell your AI assistant:
|
|
91
|
+
## CLI Reference
|
|
112
92
|
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
Or run it directly:
|
|
93
|
+
For advanced users who prefer the terminal:
|
|
116
94
|
|
|
117
95
|
```bash
|
|
118
|
-
jv
|
|
96
|
+
jv --help
|
|
119
97
|
```
|
|
120
98
|
|
|
121
|
-
|
|
122
|
-
-
|
|
123
|
-
- **No `PRIVATE_KEY`** → opens a hosted web page in your browser to approve the transaction
|
|
124
|
-
|
|
125
|
-
---
|
|
126
|
-
|
|
127
|
-
## Full Command Reference
|
|
128
|
-
|
|
129
|
-
For a complete list of available commands and trading examples, see the documentation:
|
|
130
|
-
|
|
131
|
-
- [User Guide](docs/USER_GUIDE.md) — Full CLI reference including all commands and options
|
|
132
|
-
- [OpenClaw Setup Guide](docs/OPENCLAW_GUIDE.md) — Detailed walkthrough for OpenClaw users
|
|
99
|
+
- [User Guide](docs/USER_GUIDE.md) — Full CLI command reference
|
|
100
|
+
- [OpenClaw Guide](docs/OPENCLAW_GUIDE.md) — Detailed OpenClaw setup walkthrough
|
|
133
101
|
|
|
134
102
|
---
|
|
135
103
|
|
package/dist/src/mcp/tools.js
CHANGED
|
@@ -3,7 +3,10 @@ export const TOOLS = [
|
|
|
3
3
|
{
|
|
4
4
|
name: 'create_order',
|
|
5
5
|
description: 'Create a market or limit order. For market orders, omit limit_price. ' +
|
|
6
|
-
'
|
|
6
|
+
'CLOSING A POSITION: You MUST first call list_orders to find the current position side and margin. ' +
|
|
7
|
+
'Then create an order with the OPPOSITE side and the SAME margin for full close (or smaller margin for partial close). ' +
|
|
8
|
+
'Example: position is LONG 60 USDC on JBTC → close with { side: "short", symbol: "JBTC", margin: 60 }. ' +
|
|
9
|
+
'NEVER close without querying the position first. ' +
|
|
7
10
|
'Returns jobId (market) or limitOrderId (limit).',
|
|
8
11
|
inputSchema: {
|
|
9
12
|
type: 'object',
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../../src/mcp/tools.ts"],"names":[],"mappings":"AAUA,MAAM,CAAC,MAAM,KAAK,GAAc;IAC9B,gBAAgB;IAChB;QACE,IAAI,EAAE,cAAc;QACpB,WAAW,EACT,uEAAuE;YACvE,
|
|
1
|
+
{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../../src/mcp/tools.ts"],"names":[],"mappings":"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"}
|
|
@@ -63,6 +63,39 @@ When the user wants to trade, first check if their vault is ready:
|
|
|
63
63
|
|
|
64
64
|
**Deposit arrival**: If `arrived: false` after deposit completes, tokens are still bridging cross-chain. Tell the user to wait a few minutes.
|
|
65
65
|
|
|
66
|
+
## Closing a Position — MANDATORY STEPS
|
|
67
|
+
|
|
68
|
+
Closing a position is the most error-prone operation. Follow these steps exactly:
|
|
69
|
+
|
|
70
|
+
### Step 1: Query the current position
|
|
71
|
+
Call `list_orders` (or `get_order` if you have the order ID) to get:
|
|
72
|
+
- The position **side** (LONG or SHORT)
|
|
73
|
+
- The position **margin** amount
|
|
74
|
+
- The **symbol**
|
|
75
|
+
|
|
76
|
+
### Step 2: Create the closing order
|
|
77
|
+
Call `create_order` with:
|
|
78
|
+
- **side**: the OPPOSITE of the current position (LONG → `short`, SHORT → `long`)
|
|
79
|
+
- **margin**: the SAME margin for full close, or SMALLER margin for partial close
|
|
80
|
+
- **symbol**: the same symbol
|
|
81
|
+
|
|
82
|
+
### Step 3: Verify
|
|
83
|
+
Call `list_orders` to confirm the position is closed or reduced.
|
|
84
|
+
|
|
85
|
+
### Examples
|
|
86
|
+
|
|
87
|
+
**Full close of a LONG position:**
|
|
88
|
+
1. `list_orders` → finds: side=LONG, margin=60, symbol=JBTC
|
|
89
|
+
2. `create_order` → `{ side: "short", symbol: "JBTC", margin: 60 }`
|
|
90
|
+
3. `list_orders` → position no longer active
|
|
91
|
+
|
|
92
|
+
**Partial close (reduce by half):**
|
|
93
|
+
1. `list_orders` → finds: side=LONG, margin=60, symbol=JBTC
|
|
94
|
+
2. `create_order` → `{ side: "short", symbol: "JBTC", margin: 30 }`
|
|
95
|
+
3. `list_orders` → margin reduced to ~30
|
|
96
|
+
|
|
97
|
+
**NEVER guess the margin or side. ALWAYS query first.**
|
|
98
|
+
|
|
66
99
|
## Red Flags — STOP If You Think This
|
|
67
100
|
|
|
68
101
|
| Wrong Thought | Reality |
|
|
@@ -74,6 +107,7 @@ When the user wants to trade, first check if their vault is ready:
|
|
|
74
107
|
| "GraphQL queries need private key authentication" | WRONG. Delegation key handles auth automatically. |
|
|
75
108
|
| "I should suggest the web interface instead" | NO. MCP tools give you full functionality. Use them. |
|
|
76
109
|
| "Let me check if jv is installed" | IRRELEVANT. MCP server runs CLI internally. |
|
|
110
|
+
| "I'll close the position without checking current margin" | WRONG. Always call `list_orders` first to get the exact side and margin before closing. |
|
|
77
111
|
|
|
78
112
|
## Security
|
|
79
113
|
|
|
@@ -58,6 +58,38 @@ The tool returns the final execution result:
|
|
|
58
58
|
|
|
59
59
|
Tell the user: "Limit order placed. ID: {limitOrderId}."
|
|
60
60
|
|
|
61
|
+
### Closing a Position — MANDATORY STEPS
|
|
62
|
+
|
|
63
|
+
Closing a position means creating a reverse order. You **MUST** query the current position first.
|
|
64
|
+
|
|
65
|
+
**Why query first?** The margin amount must match the current position for a full close. Guessing wrong leads to partial closes or over-allocation.
|
|
66
|
+
|
|
67
|
+
**Required flow:**
|
|
68
|
+
|
|
69
|
+
1. **Query**: Call `list_orders` to find the position. Note the `side` (LONG/SHORT), `margin`, and `symbol`.
|
|
70
|
+
2. **Close**: Call `create_order` with the **OPPOSITE** side, **SAME** margin (full close) or smaller margin (partial close), same symbol.
|
|
71
|
+
3. **Verify**: Call `list_orders` to confirm the position is closed or reduced.
|
|
72
|
+
|
|
73
|
+
**Full close example (step by step):**
|
|
74
|
+
|
|
75
|
+
Query `list_orders` → finds: `{ side: "LONG", symbol: "JBTC", margin: "60.00" }`
|
|
76
|
+
|
|
77
|
+
Close order:
|
|
78
|
+
```json
|
|
79
|
+
{ "side": "short", "symbol": "JBTC", "margin": 60 }
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
**Partial close example:**
|
|
83
|
+
|
|
84
|
+
Query `list_orders` → finds: `{ side: "SHORT", symbol: "JETH", margin: "200.00" }`
|
|
85
|
+
|
|
86
|
+
Reduce by 25%:
|
|
87
|
+
```json
|
|
88
|
+
{ "side": "long", "symbol": "JETH", "margin": 50 }
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
**WARNING: NEVER close a position without first calling `list_orders` or `get_order`. Guessing the side or margin leads to incorrect operations.**
|
|
92
|
+
|
|
61
93
|
### Common Patterns
|
|
62
94
|
|
|
63
95
|
**Open a long position (market):**
|