Skip to content

Trader Integration Overview

Jasper Vault provides a command-line tool, jv (npm package jaspervault_cli), for trading perpetuals from a terminal, a script, or an AI agent.

Feature Command
View tradable markets and live prices jv market list, jv price
Perpetual market and limit orders; add to, reduce, and close positions jv order create, jv order close
Take profit and stop loss jv tp set, jv sl set
Perpetual Protect (PP): attach a PPO when opening a position, or add one to an existing position --ppo flags, jv order protect
Deposit from Base and withdraw to Base: the command gives you a web address, and you sign with your wallet on that page jv deposit, jv withdraw
Check positions, limit orders, TP/SL orders, and market order results jv orders, jv limit-order, jv job status

Both share the same local authorization, so you only need to authorize once. The CLI connects to the Jasper Vault production environment by default; in the CLI, this environment is called beta.

After you run jv enable:

  1. The CLI randomly generates a new private key on your computer, called the delegation key. It has nothing to do with your wallet’s private key.
  2. The CLI gives you a URL. Open it in your browser, connect your wallet, and sign an authorization message that registers the delegation key as an authorized signer for your wallet. This step is only a signature: your wallet does not send any transfer transaction, and your wallet’s private key never leaves your wallet.
  3. From then on, opening and closing positions and setting take profit and stop loss are all signed locally by the delegation key, with no more wallet pop-ups.

Operations the CLI signs with the delegation key include:

  • Creating your Jasper Vault account during authorization
  • Opening, adding to, reducing, and closing positions, including limit orders and TP/SL orders
  • Buying PPO for a position

The contracts accept delegation-key signatures for a wider range of operations than the CLI uses, including adding margin, moving funds into your PP Prepaid Balance, and creating option offers.

All of these operations use funds in your account, and mistaken or malicious instructions can cause losses. Until the authorization expires, anyone who obtains this key can perform these operations with your account. Protect it as you would any credential that can move the funds in your account.

The delegation key cannot sign withdrawals. The contracts require withdrawal signatures to come from your wallet itself, and a withdrawal signed by the delegation key is rejected. jv withdraw also opens a web page so that you sign with your wallet in the browser.

  • The authorization has an expiry time, set in the deadline field of the authorization message. You can see it in your wallet’s signature request before you sign. After it expires, the contracts no longer accept signatures from this key, and orders will fail. It is currently 7 days after you sign.
  • After it expires, run jv enable again and sign with your wallet to renew. The CLI keeps using the same key.
  • The CLI currently has no command to revoke authorization. Deleting the local key file or wallet profile only deletes files on your computer; it does not invalidate the on-chain authorization.

The delegation key is stored in plain text at ~/.jaspervault/profiles/<wallet-profile>/keys.json. The CLI sets the file permissions so that only the current user can read and write it, but this may not succeed on Windows.

  • Never send this file or its contents to anyone, and never paste it into an AI conversation.
  • Do not put ~/.jaspervault/ in a Git repository, a cloud-synced folder, or a shared drive.
  • If you suspect the file has leaked, withdraw your funds to Base as soon as possible on the web app or with jv withdraw. Withdrawals require your wallet’s own signature; the delegation key cannot sign them.
  • Node.js 18 or later
  • A browser wallet, such as MetaMask or Rabby
  • Assets on Base to deposit, plus ETH to pay gas

Before trading, read the Important Risk Notice.

  1. Install the jv CLI and complete authorization
  2. Deposit and Withdraw with the CLI
  3. Trade from the Command Line, or Trade with AI Agents
  4. Before writing automated trading programs, read Write Scripts and Trading Bots; look up commands and errors in the Command Reference