Skip to content

Write Scripts and Trading Bots

  • Results are written to stdout, as single-line JSON by default, one object per line. --pretty prints indented output that spans multiple lines, so do not use it in scripts.
  • Exceptions: jv market list prints a text table by default and outputs JSON only with --json; jv install and jv update print text.
  • Messages are written to stderr, including the estimate when placing an order, flag warnings, the status line printed every 10 seconds while waiting for a browser signature, error messages (starting with Error:), and new-version notices. Read only stdout when parsing results.
  • Prices and amounts are mostly strings, for example "price":"64073.95". Handle priceWei and large integers in raw order fields as strings or big integers; do not convert them to floating-point numbers.
Command stdout
Market order jv order create (without --limit-price) Two lines: the submission receipt (with jobId) and the execution result (with status and transactionHash)
jv order protect Two lines: the submission receipt (with jobId) and the execution result
Limit order jv order create --limit-price, jv tp set, jv sl set One line, with limitOrderId
jv order close One line: {"closed":[…],"failed":[…]}
jv enable, jv deposit, jv withdraw One line first (with url), then one more line with the result when done
Other query commands One line

If a command fails before submission (invalid flags, a request rejected by the API, and so on), stdout may be empty, and the reason appears only in stderr.

Read the price:

jv price --symbol JVBTC | jq -r .price

Read the receipt and the result of a market order separately:

out=$(jv order create --side long --symbol JVBTC -m 50 --leverage 10)
code=$?
job_id=$(printf '%s\n' "$out" | head -n 1 | jq -r .jobId)
status=$(printf '%s\n' "$out" | tail -n 1 | jq -r .status)
Exit code Meaning
0 Success
1 Flag or configuration error: a required flag is missing, a flag value is invalid, the active wallet profile is not authorized yet, BASE_HTTP_RPC_URL is missing, and so on
2 Network or HTTP error: a request timed out, the service is unreachable, or the HTTP status code is not 2xx; jv price also returns 2 when it cannot get a price
3 Business error: the API rejected the request, a market order’s execution result is not completed, jv order close left a position unclosed, or authorization, a deposit, or a withdrawal was not completed

The exit code of order commands (jv order create, jv order close, jv order protect, jv tp set, jv sl set) does not tell you directly whether the order was filled. Only the following count as clear success:

  • the execution result of a market order or jv order protect is "status": "completed";
  • a limit order or TP/SL order returns a limitOrderId;
  • failed in the output of jv order close is empty.

Treat every other case as an unknown result; the order may already have been accepted or even filled:

  • Exit code 2: on a request timeout or network error, the order request may already have reached the server.
  • "status": "timeout": no execution result was received within 60 seconds; the order may still be executing.
  • "status": "failed": the order may have failed, or the CLI may have hit an HTTP or network error while querying the execution result even though the order itself was filled.

In these cases, check with jv orders list and jv limit-order list first, then decide whether to resubmit.

Also note that jv job status always returns 0, even when it finds failed or timeout; read the status field to tell.

  • Each HTTP request times out after 30 seconds by default; adjust this with the JV_TIMEOUT environment variable (in milliseconds).
  • After a market order or jv order protect is submitted, the CLI waits up to 60 seconds for the execution result.
  • The CLI never retries orders automatically. Your program should not retry automatically when the result is unknown either; check first.

After each command (except jv mcp and jv update), the CLI checks for a new version: if more than 24 hours have passed since the last check, it sends one request to the npm registry (registry.npmjs.org, waiting up to 5 seconds) and caches the result in ~/.jaspervault/update-check.json. If a new version is available, it prints a notice to stderr. The check also runs when the CLI is called through MCP.

Latency-sensitive programs should account for this request. A change in CLI version can change commands and output, so pin the version in production:

npm i -g jaspervault_cli@1.4.0
# or run a specific version each time
npx -y jaspervault_cli@1.4.0 price --symbol JVBTC
  • No dry run: a command submits a real order as soon as it runs.
  • No client order IDs or idempotency keys: running the same command twice places two orders.
  • No batch orders: jv order close --all also submits orders one at a time in sequence.
  • No market data push: poll prices with jv price.
  • No command to check account balances.
  • Submit orders for the same wallet one at a time, and wait for each result before submitting the next.
  • Fetch the latest price with jv price before placing an order; do not use a stale cached price.
  • Log every order: the full command, every line of stdout, stderr, and the exit code.
  • After the authorization expires, you need to run jv enable again. This step requires signing with your wallet in the browser and cannot be done unattended, so long-running bots should schedule renewal in advance. The authorization is currently valid for 7 days. The expiry time is in the deadline field of the signature request (Unix seconds). The CLI does not store it, so record it yourself when you sign.