Trading

check_orderCopy Anchor Link

Preflight an order without placing it: amount/contracts, min notional, free margin, leverage cap, liquidation vs stop, protection plan (native|worker), equity-guard state. Same checks place_order runs. Requires analytics or trade capability (Pro and above).

Capability: analytics or trade · read-only · REST: POST /v1/tools/check_order

Example request:

{
  "symbol": "BTC/USDT:USDT",
  "side": "buy",
  "type": "market",
  "size_usdt": 0
}

place_orderCopy Anchor Link

Place an order sized in USDT (size_usdt) with optional stop_loss/take_profit/trailing/ratchet, expires_at, leverage, margin_mode, post_only, reduce_only, position_side. Per-call notional is capped. Never flips or widens implicitly. Response reports protection modes. dry_run defaults to true: nothing is sent to the exchange until dry_run:false is passed explicitly. Responses on a simulated connection carry mode:"simulated". Requires the trade capability (Pro and above; simulated connections may trade on every tier).

Capability: trade · mutating · REST: POST /v1/tools/place_order

Example request:

{
  "symbol": "BTC/USDT:USDT",
  "side": "buy",
  "type": "market",
  "size_usdt": 0,
  "dry_run": true
}

close_positionCopy Anchor Link

Close a position by position_uid with a reduce-only market order. dry_run defaults to true: nothing is sent to the exchange until dry_run:false is passed explicitly. Responses on a simulated connection carry mode:"simulated". Requires the trade capability (Pro and above; simulated connections may trade on every tier).

Capability: trade · mutating · REST: POST /v1/tools/close_position

Example request:

{
  "position_uid": "<position_uid>",
  "dry_run": true
}

partial_closeCopy Anchor Link

Reduce a position by size_usdt or fraction (exactly one); position_uid is unchanged. dry_run defaults to true: nothing is sent to the exchange until dry_run:false is passed explicitly. Responses on a simulated connection carry mode:"simulated". Requires the trade capability (Pro and above; simulated connections may trade on every tier).

Capability: trade · mutating · REST: POST /v1/tools/partial_close

Example request:

{
  "position_uid": "<position_uid>",
  "dry_run": true
}

close_all_positionsCopy Anchor Link

Flatten all (or symbol/market_type-filtered) positions with reduce-only markets and cancel their protection orders. dry_run defaults to true: nothing is sent to the exchange until dry_run:false is passed explicitly. Responses on a simulated connection carry mode:"simulated". Requires the trade capability (Pro and above; simulated connections may trade on every tier).

Capability: trade · mutating · REST: POST /v1/tools/close_all_positions

Example request:

{
  "dry_run": true
}

reverse_positionCopy Anchor Link

Close and open the opposite side as one explicit operation (never implicit). Returns REVERSE_PARTIAL if the close succeeded but the opposite leg did not. dry_run defaults to true: nothing is sent to the exchange until dry_run:false is passed explicitly. Responses on a simulated connection carry mode:"simulated". Requires the trade capability (Pro and above; simulated connections may trade on every tier).

Capability: trade · mutating · REST: POST /v1/tools/reverse_position

Example request:

{
  "position_uid": "<position_uid>",
  "dry_run": true
}

cancel_orderCopy Anchor Link

Cancel an open order by order_id. dry_run defaults to true: nothing is sent to the exchange until dry_run:false is passed explicitly. Responses on a simulated connection carry mode:"simulated". Requires the trade capability (Pro and above; simulated connections may trade on every tier).

Capability: trade · mutating · REST: POST /v1/tools/cancel_order

Example request:

{
  "order_id": "<order_id>",
  "dry_run": true
}

modify_pending_orderCopy Anchor Link

Change price/trigger/SL/TP/expiry of a pending order; retrofitting expiry works (worker-enforced where not native). dry_run defaults to true: nothing is sent to the exchange until dry_run:false is passed explicitly. Responses on a simulated connection carry mode:"simulated". Requires the trade capability (Pro and above; simulated connections may trade on every tier).

Capability: trade · mutating · REST: POST /v1/tools/modify_pending_order

Example request:

{
  "order_id": "<order_id>",
  "dry_run": true
}

set_leverageCopy Anchor Link

Set leverage for a symbol (capped by connection/tier/exchange). Increases are blocked while the equity guard is breached. dry_run defaults to true: nothing is sent to the exchange until dry_run:false is passed explicitly. Responses on a simulated connection carry mode:"simulated". Requires the trade capability (Pro and above; simulated connections may trade on every tier).

Capability: trade · mutating · REST: POST /v1/tools/set_leverage

Example request:

{
  "symbol": "BTC/USDT:USDT",
  "leverage": 1,
  "dry_run": true
}

set_margin_modeCopy Anchor Link

Set isolated/cross margin for a symbol; rejected while a position is open on it. dry_run defaults to true: nothing is sent to the exchange until dry_run:false is passed explicitly. Responses on a simulated connection carry mode:"simulated". Requires the trade capability (Pro and above; simulated connections may trade on every tier).

Capability: trade · mutating · REST: POST /v1/tools/set_margin_mode

Example request:

{
  "symbol": "BTC/USDT:USDT",
  "margin_mode": "isolated",
  "dry_run": true
}

set_position_modeCopy Anchor Link

Switch one-way/hedge mode; rejected while any position or order is open. dry_run defaults to true: nothing is sent to the exchange until dry_run:false is passed explicitly. Responses on a simulated connection carry mode:"simulated". Requires the trade capability (Pro and above; simulated connections may trade on every tier).

Capability: trade · mutating · REST: POST /v1/tools/set_position_mode

Example request:

{
  "mode": "oneway",
  "dry_run": true
}