preview_perp_order
Preview a perpetual futures order · read-only ·
scopes: trade:propose
Check a perpetual futures order with its stop-loss (optional take-profit) against this agent's permissions, the person's limits and the price band, sending nothing. Use before every new position, also one that waits for a price (trigger_price). Not for closing (use close_perp_position_reduce_only). size_base (base coin): from size_position_by_risk; the stop: stop_loss (USD) or stop_pct. Returns preview_id (valid 30 s), notional, risk, margin, likely fill and every check; a rejection names the failing check and, when a fix is certain, suggested_args. Next: execute_previewed_order(preview_id).
Call it
MCP tools/call
{"name": "preview_perp_order", "arguments": {"symbol": "BTC", "side": "buy", "size_base": 0.01}}REST
POST /v1/orders/preview
{"symbol": "BTC", "side": "buy", "size_base": 0.01}Inputs
| Name | Meaning (* required) |
|---|---|
symbol * | Base coin, e.g. BTC |
side * | buy = open or add to a long, sell = open or add to a short |
size_base * | Size in the base coin (BTC, not USD); rounded down to the venue step. Get it from size_position_by_risk |
stop_loss | Required stop-loss, USD per coin: below entry for buys, above for sells. Or give stop_pct |
stop_pct | Or the stop as a distance from the entry (trigger price, limit price or mark), 0.02 = 2% |
venue | Venue: sandbox, hyperliquid, okx, bybit or binance. Omitted: the agent's only venue, else hyperliquid, else your only connected venue, else sandbox; or "best": the cheapest all-in venue (price plus fee) you may use and have the margin for |
order_type | |
price | Limit price, USD per coin (limit orders only) |
leverage | Leverage, e.g. 5 |
take_profit | Optional take-profit, USD per coin |
trigger_price | Optional: hold the order and open it at market only when the mark reaches this price (a breakout or a pullback), re-checked then; market orders only. Risk is computed from this price |
trigger_valid_hours | With trigger_price: hours it waits before lapsing, 1-168 (default 24) |
reason | Optional: why, in your words (up to 500 characters). The person sees it on the approval card and in history; other agents never do |
hold_hours | Optional: how long you expect to hold, in hours, to see funding and the round trip's cost (and, with venue "best", to choose by them) |
Returns
| Field | Meaning and unit |
|---|---|
ok | True: every check passed |
preview_id | Pass to execute_previewed_order within 30 seconds |
expires_at | ISO 8601 UTC |
venue | Venue name |
symbol | Base coin |
side | buy or sell |
size | Size after rounding down to the venue step, in the base coin (e.g. BTC), not USD |
mark_price | Mark at preview time, USD per coin |
notional_usd | size x entry, USD |
risk_usd | Loss if the stop fills, USD |
margin_usd | Margin needed, USD |
est_fill_price | Market orders: average fill if executed now against the book, USD per coin; null for limit orders or when the book is too thin to say |
est_slippage_bps | est_fill_price against mark_price in basis points, positive = worse; a market order never fills beyond the price band |
est_fee_usd | Trading fee for this order, USD: taker rate for market orders, maker for limit; the exit pays a fee too |
fee_rate_bps | The rate used, basis points of notional |
fee_source | account (your own rate), published (the base rate) or none (sandbox) |
venue_choice | With venue "best": why this venue (all-in price and the alternatives) |
est_funding_usd | With hold_hours: funding over that time at today's rate, USD; negative = received |
est_round_trip_cost_usd | With hold_hours: entry fee, exit fee at the taker rate and that funding, USD |
requires_approval | True: execute_previewed_order will wait for a person's approval |
trigger_price | A trigger entry: opens at market only when the mark reaches this, USD per coin |
trigger_valid_hours | A trigger entry: hours it waits before lapsing |
checks | Every check that ran, all pass |
Rejections: error codes, each with what to do.