Write Scripts and Trading Bots
Output format
Section titled “Output format”- Results are written to stdout, as single-line JSON by default, one object per line.
--prettyprints indented output that spans multiple lines, so do not use it in scripts. - Exceptions:
jv market listprints a text table by default and outputs JSON only with--json;jv installandjv updateprint 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". HandlepriceWeiand large integers in raw order fields as strings or big integers; do not convert them to floating-point numbers.
How many lines each command prints
Section titled “How many lines each command prints”| 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:
Read the receipt and the result of a market order separately:
Exit codes
Section titled “Exit codes”| 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 protectis"status": "completed"; - a limit order or TP/SL order returns a
limitOrderId; failedin the output ofjv order closeis 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.
Timeouts and retries
Section titled “Timeouts and retries”- Each HTTP request times out after 30 seconds by default; adjust this with the
JV_TIMEOUTenvironment variable (in milliseconds). - After a market order or
jv order protectis 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.
Update checks
Section titled “Update checks”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:
Features not available yet
Section titled “Features not available yet”- 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 --allalso submits orders one at a time in sequence. - No market data push: poll prices with
jv price. - No command to check account balances.
Recommendations
Section titled “Recommendations”- 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 pricebefore 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 enableagain. 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 thedeadlinefield of the signature request (Unix seconds). The CLI does not store it, so record it yourself when you sign.