Futures-Specific Fields

Nine fields that mean nothing on spot but everything on derivatives. Leverage, margin mode, the Binance dual-position-mode flag, OKX positionSide, and the postOnly default-true trap that catches first-timers.

TL;DR

• postOnly defaults to true. Marketable limit prices are rejected silently. Set postOnly: false if your limit must fill aggressively.
• Set leverage and marginType on the entry that opens the position, not on follow-up payloads. Most exchanges reject changes while a position is open.
• hedgeMode: true is Binance Futures dual-position mode. It changes the routing semantics — you then need closeLong / closeShort for hedge-mode exits.
• OKX uses positionSide (net / long / short) and instrumentType (spot / margin / futures / swap / options).

Spot exchanges ignore futures fields

Sending leverage: 10 on exchange: "binance" (spot) does nothing — the field is silently dropped by the spot adapter. Same for marginType, hedgeMode, reduceOnly, workingType, positionSide, instrumentType. No error. Test on the right exchange identifier.

Quick reference table

Property	Type	Required	Default	Description
leverage	decimal	no	0	Leverage multiplier to apply before placing the order. TVH updates the exchange-side leverage for the pair only if the requested value differs from the current setting.
marginType	string	no	—	Per-pair margin mode for the trade. Switches the exchange setting before placing the order if required.
reduceOnly	bool	no	false	Mark the order as reduce-only — it can shrink but never increase a position. Used by SL/TP follow-ups and trailing-stop logic.
postOnly	bool	no	true	Reject the order if it would take liquidity (= ensures maker fee tier). Default is true in TVH; flip to false for limits that must fill aggressively.
hedgeMode	bool	no	false	Binance Futures dual-position mode. When true the account allows simultaneous long + short positions and routing uses positionSide instead of net direction.
margin	bool	no	false	Flag used by spot-margin adapters to mark the trade as a margin order rather than plain spot. Currently consumed by KuCoin margin and similar adapters.
workingType	string	no	mark	Binance Futures only. Which price triggers SL/TP stop orders. mark is the index/mark price (safer); contract is the last trade price.
instrumentType	string	no	—	OKX-only product family. Controls which OKX endpoint is used for the order.
positionSide	string	no	net	OKX-only side tag. net for one-way mode, long or short when the account runs hedge-mode separately.

The postOnly default trap

The biggest single source of "TVH didn't fill my limit order" tickets.

postOnly defaults to true when you omit it. That means every limit order — unless you explicitly say otherwise — is sent as maker-only. If your limit price would cross the spread and take liquidity, the exchange rejects it. TVH logs the rejection but you don't get a position.

This is intentional. Maker-only orders earn the maker rebate, and most algorithmic entries are placed off the touch with the expectation they fill later. But it surprises anyone copy-pasting a JSON snippet from another tool where the default is the opposite.

Two fixes:

1. Disable for marketable limits. Set postOnly: false when you want the limit to fill at the touch (or cross it for guaranteed fill).

   { "isLimit": true, "price": 65000, "postOnly": false }

2. Use limit-chase. Keep postOnly: true but enable chaseLimitOrder: true. The chase loop re-prices to the moving best bid/ask so the order stays maker-side. See Limit Order Management.

Leverage and margin mode

{
  "leverage": 10,
  "marginType": "isolated"
}

TVH updates the exchange-side leverage for the pair only if the requested value differs from the current setting. Same for margin type. Both updates happen before the entry order is submitted.

Most exchanges block these changes while a position is open (Binance, Bybit, OKX, KuCoin all reject). Set leverage and margin on the entry that opens the position, not on add-on or DCA payloads.

Per-exchange leverage caps (May 2026):

Exchange	Max leverage	Notes
Binance Futures USDT-M	125x	Capped per-pair; high-leverage tiers have lower size caps.
Binance Futures COIN-M	125x	Same tiering as USDT-M.
Bybit USDT/USDC Perps	100x	UTA accounts share margin.
Bybit Inverse	100x
OKX Perp	125x	Some pairs lower.
KuCoin Futures	100x	Most pairs 20-50x.
Coinbase Perps	20x	Hard cap.
BitMEX	100x	Per-pair.

Asking for a value above the per-pair cap is silently capped by the exchange — TVH logs the actual leverage applied. No exception thrown.

Hedge mode (Binance Futures dual-position)

By default a Binance Futures account is one-way: a long and short on the same pair net out. Hedge mode lets you hold both simultaneously, each with its own SL/TP. It's an account-level setting — hedgeMode: true only toggles when no positions are open, and closing then requires closeLong / closeShort to pick a side.

Order's position side does not match user's setting. Code: -4061

The classic Binance mismatch: your account is in hedge mode but the trade is one-way, or vice versa. Set your account to the matching mode, or set hedgeMode so the payload matches. See Debug a Failed Alert.

The full cross-exchange walkthrough — Binance enabling, OKX positionSide, Bybit account-level, direction-aware close, and use cases — is on Hedge Mode.

OKX position side and instrument type

OKX has two side-related fields where Binance has one.

{
  "exchange": "okx",
  "instrumentType": "swap",
  "positionSide": "net"
}

• instrumentType picks the OKX product family the order is routed to. Match it to the pair suffix:

  Pair format	instrumentType
  BTC-USDT-SWAP	swap
  BTC-USD-241225 (dated futures)	futures
  BTC-USDT	spot (or margin for cross/iso margin)
  BTC-USDT-241225-50000-C	options

• positionSide disambiguates side when OKX is in hedge mode. net (default) = one-way mode. long / short = hedge mode.

OKX's "hedge mode" is a per-account setting independent of Binance's. The two are not linked. Switching is done via OKX's account settings, not via a TVH payload field.

Detail per property

leverage

Attribute	Value
Type	decimal
Required	no
Default	0 (= "leave at current")
TV placeholder compatible	no

Leverage multiplier. 0 means "don't touch the exchange-side setting". Any positive value triggers a leverage-update call before the entry submits.

marginType

Attribute	Value
Type	string
Required	no
Allowed values	"isolated", "cross" (Bybit also accepts "crossed")
Default	"" (= "leave at current")
TV placeholder compatible	no

Per-pair margin mode. Empty string = don't touch.

Casing. Most exchanges normalise the value, so "isolated" (lowercase) works everywhere. The one outlier is Hyperliquid, which expects the exact string "ISOLATED" and defaults to isolated when the field is null. On that exchange specifically, send the uppercase form if you want to be explicit.

hedgeMode

Attribute	Value
Type	bool
Required	no
Default	false

Binance Futures account-level dual-position mode. Affects whether you use closeCurrentPosition (one-way) or closeLong / closeShort (hedge) to exit.

reduceOnly

Attribute	Value
Type	bool
Required	no
Default	false

Marks the order as reduce-only — it can shrink but never increase a position. TVH sets this automatically for SL/TP follow-up orders; you rarely set it by hand.

postOnly

Attribute	Value
Type	bool
Required	no
Default	true

Reject the order if it would take liquidity (maker fee tier). Default is true. See the warning at the top of this page.

workingType

Attribute	Value
Type	string
Required	no
Allowed values	"mark", "contract"
Default	"mark"

Binance Futures only. Which price triggers SL/TP stop orders:

• mark (default, safer) — the index/mark price. Less susceptible to single-exchange wicks.
• contract — the last trade price on Binance. Reacts faster, more wick-prone.

Use mark unless you have a specific reason for contract.

positionSide

Attribute	Value
Type	string
Required	no
Allowed values	"net", "long", "short"
Default	"net"

OKX-only side tag. net for one-way mode, long / short for hedge mode.

instrumentType

Attribute	Value
Type	string
Required	conditional (OKX only)
Allowed values	"spot", "margin", "futures", "swap", "options"
Default	""

OKX-only product family. Match it to the pair suffix.

margin

Attribute	Value
Type	bool
Required	no
Default	false

Flag used by spot-margin adapters (KuCoin margin) to mark the trade as a margin order rather than plain spot. Most users leave this alone; the Trade Command Builder sets it when you pick a margin-enabled pair.

Common mistakes

• Setting leverage on a position-add payload. Binance / Bybit / OKX reject the leverage update because a position is already open. The entry then submits with the old leverage. Set leverage only on the entry that opens the position.
• Forgetting postOnly: false. Limit orders at the touch get rejected silently. Either flip the flag or enable chaseLimitOrder to stay maker-side.
• Mixing hedgeMode: true with one-way close payloads. A hedge-mode account ignores closeCurrentPosition (one-way semantics) — use closeLong / closeShort.
• OKX instrumentType doesn't match the pair. pair: "BTC-USDT-SWAP" with instrumentType: "futures" returns "instrument not found". Match them.
• Trying to enable hedge mode with an open position. Binance rejects. Flatten first.

Next

DCA & Scaled Orders — entry meshes and scaled-limit ladders for accumulation patterns.