Sizing — Units, Percent, Fixed Quote

Controls how big the trade is. Six fields, three mental models: absolute base-asset quantity, percent of available balance, or a fixed quote-currency amount.

TL;DR

• Default sizing model is unitsType: "absolute" — units is the base-asset quantity (e.g. 0.01 = 0.01 BTC).
• For percent-of-balance sizing, set unitsType: "percent" and put the percent in unitsPercent (or in units).
• For "spend exactly $100 worth of BTC", set useFixedSize: true and fixedQuoteSize: 100.
• useEntireAccountBalance is Bybit-UTA-only. Other exchanges ignore it silently.

TradingView placeholders

units, unitsPercent and fixedQuoteSize accept Pine placeholders (e.g. {{strategy.order.contracts}}). See Anatomy → Dynamic values via TradingView placeholders.

Quick reference table

Property	Type	Required	Default	Description
units	decimal	conditional	0	Position size. Interpretation depends on unitsType (absolute base units, percent of balance, or risk-based).
unitsType	string	no	absolute	How to interpret units. absolute = base-asset quantity, percent = percent of available margin/balance, percentBalance = percent of total balance, percentWallet = percent of wallet equity, percentPosition = percent of current open position (close/scale-out only), risk = derive size from stopLoss distance.
unitsPercent	decimal	no	0	Convenience field equivalent to units when unitsType="percent". Provided as a separate property so Pine alert messages can hard-code a percentage without flipping the type flag.
useFixedSize	bool	no	false	Override units/unitsType with a fixed quote-currency amount from fixedQuoteSize. Useful for dollar-cost-style entries that ignore current balance.
fixedQuoteSize	decimal	conditional	0	Quote-currency amount when useFixedSize is true (e.g. 100 = $100 of BTC at the current mark price).
useEntireAccountBalance	bool	no	false	Bybit UTA-only shortcut to size the entry using the full available balance after reservations. Ignores units and fixedQuoteSize.

The sizing models

You pick a mode by setting unitsType (or by flipping useFixedSize / useEntireAccountBalance). The three most common modes are documented here; percentBalance, percentWallet, and percentPosition are minor variants of Mode B with different denominators — see the unitsType detail.

Mode A — absolute base-asset quantity (default)

{
  "unitsType": "absolute",
  "units": 0.05
}

Trades 0.05 base-asset units. On BTCUSDT that's 0.05 BTC. On ETHUSDT it's 0.05 ETH. The base asset is the left side of the pair name.

Use this when:

• You compute position size off-chain (e.g. a Python pre-trade script) and want an exact quantity on the wire.
• Your Pine strategy hard-codes contract size and you pass {{strategy.order.contracts}} straight through.

Mode B — percent of balance

Put the percentage in unitsPercent and pick an explicit percent variant:

{
  "unitsType": "percentBalance",
  "unitsPercent": 95
}

unitsType	Sizes against
percentBalance	Free / available balance — excludes margin locked in open positions. The safe default.
percentWallet	Total wallet balance (incl. locked margin), then capped at what's actually available.
percent	Legacy / ambiguous — avoid. On Binance, Bybit, OKX and BitMEX it falls through to the wallet total (like percentWallet); on KuCoin, Coinbase and Hyperliquid it is not recognised and the order is rejected. Always send percentBalance or percentWallet.

TVH queries the exchange for the live balance at submission time and converts the percent to base-asset units. The %Balance vs %Wallet difference: with $1,000 in your futures wallet and $300 locked in an open position, percentBalance: 50 sizes off $700 ($350), while percentWallet: 50 sizes off $1,000 ($500).

Use 95%, not 100%

Leave headroom for fees, slippage and rounding so the order isn't rejected at the exchange edge.

Watch out:

• On futures, leverage is applied after the percent calculation: 5% of balance at 10x leverage commits 5% as margin and opens ~50% notional exposure.
• TVH does not auto-cap at 100%. Asking for 110% gets you rejected by the exchange, not throttled by TVH.
• unitsPercent is the field read in percent modes. units only carries the base-asset quantity in absolute mode (a Pine template can still pass "units": "{{strategy.order.contracts}}" for absolute fills).

Mode C — fixed quote-currency amount

{
  "useFixedSize": true,
  "fixedQuoteSize": 100
}

Spend exactly 100 quote units — typically 100 USDT on a BTCUSDT pair. TVH divides by the current mark price to get base-asset quantity, then submits.

Use this for dollar-cost-style entries where you want consistent notional exposure regardless of price action between alerts.

Watch out:

• Some exchanges only natively support quote-sizing on certain order types. The supported matrix is in the table below.
• When useFixedSize=true, the units / unitsType / unitsPercent fields are ignored.

Bybit-only shortcut: entire account balance

{ "useEntireAccountBalance": true }

Sizes the entry to the full available balance after reservations. Bybit UTA accounts only. On any other exchange, the flag is silently ignored — the trade falls back to whatever units / unitsType say.

Use sparingly. With leverage on, this puts the account at maximum exposure.

Per-exchange sizing support

Native support for each mode varies by exchange. TVH tries to emulate where it can, but the matrix is worth knowing.

Exchange	absolute	percent	useFixedSize	useEntireAccountBalance
Binance Spot	yes	yes	yes (via quoteOrderQty)	no
Binance Futures USDT-M	yes	yes	yes	no
Binance Futures COIN-M	yes	yes	partial (contract size rounding)	no
Bybit (UTA)	yes	yes	yes	yes
Bybit Spot	yes	yes	yes	no
OKX	yes	yes	yes	no
KuCoin Futures	yes (contracts)	yes	yes	no
KuCoin Spot	yes	yes	yes	no
Coinbase Perps	yes	yes	yes	no
Coinbase Spot	yes	yes	yes	no
BitMEX	yes (contracts)	yes	partial	no

Worked examples

Long Binance Futures with 2% of balance

{
  "exchange": "binance-futures",
  "pair": "BTCUSDT",
  "apiKey": "binance-futures-main",
  "isBuy": true,
  "isMarket": true,
  "leverage": 10,
  "marginType": "isolated",
  "unitsType": "percentBalance",
  "unitsPercent": 2,
  "token": "<token>"
}

2% of free/available balance committed as margin at 10x = ~20% notional exposure on BTCUSDT.

$250 of ETH on Binance Spot

{
  "exchange": "binance",
  "pair": "ETHUSDT",
  "apiKey": "binance-main",
  "isBuy": true,
  "isMarket": true,
  "useFixedSize": true,
  "fixedQuoteSize": 250,
  "token": "<token>"
}

TVH divides 250 by current ETH price and submits the base-asset quantity, rounded to Binance's lot-size step.

Risk-based: lose 1% if the stop is hit

{
  "exchange": "binance-futures",
  "pair": "BTCUSDT",
  "apiKey": "binance-futures-main",
  "isBuy": true,
  "isMarket": true,
  "unitsType": "risk",
  "unitsPercent": 1,
  "stopLossType": "percent",
  "stopLossPercent": 2,
  "leverage": 10,
  "token": "<token>"
}

TVH back-solves the size so that a stop-out at −2% costs exactly 1% of total balance. Widen the stop and the size shrinks automatically. A stop loss is mandatory in risk mode.

Pine strategy.order.contracts pass-through

When you let Pine compute the size (e.g. via risk-per-trade off the bar's ATR), the cleanest payload is:

{
  "exchange": "bybit",
  "pair": "{{ticker}}",
  "apiKey": "bybit-main",
  "orderType": "{{strategy.order.action}}",
  "isMarket": true,
  "unitsType": "absolute",
  "units": "{{strategy.order.contracts}}",
  "token": "<token>"
}

{{strategy.order.contracts}} is replaced with the exact size Pine decided for this fill. The same template handles every fill the strategy produces.

Bybit UTA full balance market buy

{
  "exchange": "bybit",
  "pair": "BTCUSDT",
  "apiKey": "bybit-uta-main",
  "isBuy": true,
  "isMarket": true,
  "useEntireAccountBalance": true,
  "token": "<token>"
}

Detail per property

units

Attribute	Value
Type	decimal
Required	conditional (required unless useFixedSize=true or useEntireAccountBalance=true)
Default	0
TV placeholder compatible	yes

Position size. In absolute mode it is the base-asset quantity (BTC, ETH). In every percent mode the percentage is read from unitsPercent, not units.

unitsType

Attribute	Value
Type	string
Required	no
Allowed values	"absolute", "percentBalance", "percentWallet", "percentPosition", "risk" (plus legacy "percent")
Default	"absolute"

Sizing model and which balance pool the percent applies to:

• "absolute" → raw units as base-asset quantity. No balance lookup.
• "percentBalance" → percent of free / available balance. The safe default for percent sizing.
• "percentWallet" → percent of total wallet balance (incl. locked margin), then capped at available.
• "percentPosition" → percent of the current open position. Close / scale-out only — there's no entry position to take a percent of otherwise.
• "risk" → size back-solved from stop-loss distance so a stop-out loses unitsPercent% of the total balance. Requires stopLoss (absolute) or stopLossPercent, else the trade is rejected.
• "percent" → legacy/ambiguous, avoid. Falls through to the wallet total on Binance/Bybit/OKX/BitMEX, but is not recognised on the newer KuCoin/Coinbase/Hyperliquid adapters (order rejected). Use percentBalance or percentWallet explicitly.

unitsPercent

Attribute	Value
Type	decimal
Required	conditional (in any percent / risk mode)
Default	0
TV placeholder compatible	yes

The percentage used by percentBalance, percentWallet, percentPosition, and risk. This is the field TVH reads for percent sizing — units is only used in absolute mode.

useFixedSize

Attribute	Value
Type	bool
Required	no
Default	false

Overrides units / unitsType with a fixed quote-currency amount from fixedQuoteSize.

fixedQuoteSize

Attribute	Value
Type	decimal
Required	conditional (when useFixedSize=true)
Default	0
TV placeholder compatible	yes

Quote-currency amount when useFixedSize=true. On BTCUSDT, this is USDT. On XBTUSD (BitMEX inverse), this is contracts.

useEntireAccountBalance

Attribute	Value
Type	bool
Required	no
Default	false

Bybit UTA-only. Sizes the entry to the full available balance. Ignored on every other exchange.

Sizing pitfalls

• units is base, not quote. Sending units: 100 on BTCUSDT means 100 BTC, not $100. If you want $100, use useFixedSize.
• percentBalance vs percentWallet. percentBalance sizes off free margin (excludes locked positions); percentWallet off the total wallet. Don't send bare percent — it's wallet-total on some exchanges and rejected on others.
• Round-down to lot size. Exchanges enforce a minimum-step quantity per pair (e.g. 0.001 BTC on Binance Futures). TVH rounds down to the nearest step. A tiny percent on a tiny balance can round to zero.
• useFixedSize overrides percent. If both useFixedSize=true and unitsType="percent" are set, the fixed size wins. Pick one.

Next

Stop Loss & Trailing — attach risk to the trade you just sized.