Skip to content

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.

jv market list
SYMBOL  PAIR                 MARGIN  MAX_LEVERAGE
JVBTC   BTC/USDC             JVUSD   100x
JETH    ETH/USDC             JVUSD   50x
…
  • SYMBOL is the trading symbol; use this column for --symbol when placing orders and checking prices. Currently available: JVBTC, JETH, SKHY, XAU, TQQQ, CL, CRCL, MU, NVDA, TSLA.
  • MARGIN is the market’s margin asset, and MAX_LEVERAGE is its maximum leverage.
  • The market list ships with each CLI version; newly launched markets appear only after you upgrade with jv update.
  • Add --json for JSON output:
{"environment":"beta","markets":[{"symbol":"JVBTC","pair":"BTC/USDC","marginAsset":"JVUSD","maxLeverage":100},{"symbol":"JETH","pair":"ETH/USDC","marginAsset":"JVUSD","maxLeverage":50},…]}

Check the live price:

jv price --symbol JVBTC
{"symbol":"JVBTC","price":"64073.95","priceWei":"64073950000000000000000","source":"quote_center","timestamp":"2026-11-18T12:08:06.954Z"}

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.

# market long: margin 100, 20x leverage
jv order create --side long --symbol JVBTC -m 100 --leverage 20

# limit short: triggers when the price reaches 68000, valid for 2 hours
jv order create --side short --symbol JVBTC -m 50 --leverage 10 --limit-price 68000 --ttl 7200
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 a transactionHash. If the result is not completed, 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.

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 protect is "status": "completed";
  • a limit order or TP/SL order returns a limitOrderId;
  • failed in the output of jv order close is 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.

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 --leverage to the original position’s leverage (leverage in jv orders list).
  • margin in jv orders list is 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:

jv order create --side short --symbol JVBTC -m 50 --leverage 20

To close:

jv order close --order-id 42   # close order 42
jv order close --all           # close all positions
  • jv order close reads the position’s side, leverage, and margin (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, use jv orders list to confirm that the position is closed and that no new reverse position was opened.
  • Use either --order-id or --all, not both. --all closes 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.

# long order 42: take profit 70000, stop loss 60000
jv tp set --order-id 42 --price 70000 --symbol JVBTC
jv sl set --order-id 42 --price 60000 --symbol JVBTC

# short order 43: --side short is required
jv tp set --order-id 43 --price 58000 --symbol JVBTC --side short
jv sl set --order-id 43 --price 66000 --symbol JVBTC --side short
  • --side defaults to long. 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 with jv limit-order.

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:

jv order create --side long --symbol JVBTC -m 100 --leverage 20 --ppo
jv order create --side long --symbol JVBTC -m 100 --leverage 20 --ppo --ppo-expire 8h --ppo-category OTM --ppo-tier 3
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 --order-id 42 --symbol JVBTC
jv order protect --order-id 42 --symbol JVBTC --ppo-expire 8h --ppo-category OTM --ppo-tier 2

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 --ppo also 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 --ppo this time; to keep the protection, include --ppo in that operation too. The CLI has no separate command to cancel a PPO.
  • jv order close does not attach a PPO to the close order.
jv orders list                          # current positions (by default only open ones, 20 per page)
jv orders list --all --since 7d         # all orders from the last 7 days, including closed ones
jv orders list --position-side SHORT    # short positions only
jv orders get 42                        # a single order
jv orders stats                         # total orders, open and closed counts
  • In addition to the raw fields, each order includes readable fields: margin (margin), size (position size), entryPriceUsd (entry price), leverage (leverage), and createdTime (creation time).
  • --since and --until accept dates such as 7d, 1w, 2h, or 2025-01-01, or a Unix timestamp. Paginate with --page and --limit.
  • --position-side filters only within the current page; the returned total is not affected by it.

Limit orders and TP/SL orders:

jv wallet info                                          # show the wallet address (eoa)
jv limit-order list --wallet 0xYourWalletAddress --status PENDING
jv limit-order status <limitOrderId>
jv limit-order cancel <limitOrderId>

The statuses are PENDING, TRIGGERED, EXECUTING, COMPLETED, FAILED, EXPIRED, and CANCELLED.

Market order execution results:

jv job status <jobId>

The command waits up to 60 seconds; status is one of completed, failed, timeout, or not_found.