Trade from the Command Line
All trading commands below require authorization first. Command results are printed as single-line JSON by default; add --pretty for indented output.
While you hold a position, funding fees are paid or received according to the funding rate. If your margin is insufficient, the position will be liquidated; for the rules, see Liquidation Mechanism.
Check markets and prices
Section titled “Check markets and prices”SYMBOLis the trading symbol; use this column for--symbolwhen placing orders and checking prices. Currently available: JVBTC, JETH, SKHY, XAU, TQQQ, CL, CRCL, MU, NVDA, TSLA.MARGINis the market’s margin asset, andMAX_LEVERAGEis its maximum leverage.- The market list ships with each CLI version; newly launched markets appear only after you upgrade with
jv update. - Add
--jsonfor JSON output:
Check the live price:
price is the price, and priceWei is the integer scaled up by 10^18. --symbol must be a trading symbol; BTC returns no price, and the command exits with code 2.
Open a position: jv order create
Section titled “Open a position: jv order create”| Flag | Description |
|---|---|
--side |
Side, long or short; required |
--symbol |
Trading symbol; required |
-m, --margin |
Margin amount; required. Denominated in the market’s margin asset (the MARGIN column of jv market list) |
--leverage |
Leverage; defaults to 50x if omitted. Do not exceed the market’s MAX_LEVERAGE |
--limit-price |
Limit price; omit it for a market order |
--ttl |
Validity period of the order signature, in seconds; default 3600. A limit order that is not triggered within this period expires |
--ppo, etc. |
Attach Perpetual Protect (PP) when opening; see below |
The command prints an estimate line to stderr, for example Estimated: ~0.031214 JVBTC @ $64,073.95 (~$2,000 JVUSD total, 20x).
- Market orders: after submission, the command waits up to 60 seconds for the execution result. stdout prints two lines of JSON: the first is the submission receipt, with a
jobId; the second is the execution result, where"status": "completed"means the order has been filled on-chain, along with atransactionHash. If the result is notcompleted, the command exits with code 3, but that does not necessarily mean the order was not filled; see “When the result is unclear” below. - Limit orders: the command immediately returns one line of JSON with a
limitOrderId, and the order executes automatically when the price is reached.
When the result is unclear
Section titled “When the result is unclear”Order commands (jv order create, jv order close, jv order protect, jv tp set, jv sl set) have no protection against duplicate submission: running the same command twice places two orders. 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.
In all other cases, including exit code 2 (request timeout or network error), "status": "timeout", and "status": "failed", the order may already have been accepted or even filled. Before resubmitting, check with jv orders list and jv limit-order list.
Add to, reduce, and close positions
Section titled “Add to, reduce, and close positions”When you already have a position, a new order for the same trading symbol is handled based on its side and margin:
| New order | Result |
|---|---|
| Same side | Adds to the position |
| Opposite side, margin equal to the position’s current margin | Closes the entire position |
| Opposite side, margin greater than the position’s current margin | Closes the entire position first, then opens a new position on the opposite side with the excess; if the excess is too small, it only closes |
| Opposite side, margin less than the position’s current margin | Then compares by position size (margin × leverage ÷ entry price): if smaller than the original position, it reduces the position, closing it entirely if too little would remain; if equal, it closes the entire position; if larger, it likewise closes first and then opens in the opposite direction |
Before placing an opposite-side order, work out the margin and leverage carefully, or you may end up with a reverse position after the close:
- If you set a higher leverage than the original position’s, the position size may exceed the original even with a smaller margin. When reducing, set
--leverageto the original position’s leverage (leverageinjv orders list). margininjv orders listis the cumulative margin deposited: it grows when you add to the position and does not change when you reduce it. After you have reduced a position, it is larger than the position’s current margin and cannot be used directly to calculate the margin for reducing or closing. The CLI currently cannot query a position’s current margin, so for positions you have already reduced, we recommend continuing to reduce or close them on the web app.
For example, to reduce by half a JVBTC long with 20x leverage and 100 margin that has never been reduced:
To close:
jv order closereads the position’s side, leverage, andmargin(cumulative margin deposited) and submits an opposite-side order. For a position you have reduced, this margin is larger than the position’s current margin, so the order may be processed as a close followed by a reverse open. We recommend closing such positions on the web app.- After closing with
jv order close, usejv orders listto confirm that the position is closed and that no new reverse position was opened. - Use either
--order-idor--all, not both.--allcloses positions one at a time in order and prints one line,{"closed":[…],"failed":[…]}; if any of them fails, the exit code is 3.
The order ID is the id of each order in jv orders list.
Take profit and stop loss
Section titled “Take profit and stop loss”--sidedefaults tolong. Shorts must include--side short; otherwise, the CLI signs with the side and position account of a long.- When triggered, it closes the entire position and does not open a reverse position.
- Valid for 24 hours by default (
--ttl 86400); if it has not triggered before it expires, set it again. - Returns one line of JSON with a
limitOrderId. TP/SL orders, like limit orders, are queried and canceled withjv limit-order.
Perpetual Protect (PP): PPO flags
Section titled “Perpetual Protect (PP): PPO flags”In the CLI, Perpetual Protect (PP) works through PPO options: a long is paired with a put option (PUT) and a short with a call option (CALL), so you don’t need to choose manually. For concepts and fees, see What Is Perpetual Protect (PP)? and Protection Duration, Range, and Strength.
To attach protection when opening a position:
| Flag | Values | Default |
|---|---|---|
--ppo |
Enables protection | Off |
--ppo-expire |
30m or 8h |
30m |
--ppo-category |
ATM: the strike price equals the current price; OTM: the strike price is offset from the current price |
ATM |
--ppo-tier |
1 to 5; each tier adds a 0.1% offset, so tier 5 is a 0.5% offset |
Required with OTM; ignored with ATM |
To add protection to an existing position on its own, without changing the position size:
jv order protect first fetches a premium quote and then submits. It waits up to 60 seconds for the execution result and prints two lines to stdout: the submission receipt and the execution result.
Notes:
- To add protection to an existing position, use
jv order protect.jv order create --ppoalso adds to the position. - When you add to or reduce a position that already has a PPO, the existing PPO is canceled if you don’t include
--ppothis time; to keep the protection, include--ppoin that operation too. The CLI has no separate command to cancel a PPO. jv order closedoes not attach a PPO to the close order.
Check orders
Section titled “Check orders”- In addition to the raw fields, each order includes readable fields:
margin(margin),size(position size),entryPriceUsd(entry price),leverage(leverage), andcreatedTime(creation time). --sinceand--untilaccept dates such as7d,1w,2h, or2025-01-01, or a Unix timestamp. Paginate with--pageand--limit.--position-sidefilters only within the current page; the returnedtotalis not affected by it.
Limit orders and TP/SL orders:
The statuses are PENDING, TRIGGERED, EXECUTING, COMPLETED, FAILED, EXPIRED, and CANCELLED.
Market order execution results:
The command waits up to 60 seconds; status is one of completed, failed, timeout, or not_found.