Max Open Positions: Cap the Positions of Your Account
maxOpenPositionscaps how many positions your exchange account holds at the same time. With"maxOpenPositions": 1, an entry on a new coin is skipped while any other position is open.- Only entries on a symbol without a position are checked. Adding to an open position, closes, stop losses, take profits, reduce-only orders and cancels are never affected.
- The count reads the exchange: positions you opened by hand and positions of a bot on the same API key count too.
- Futures and spot, on every exchange except BitMEX and MT5. In the Trade Command Builder it is the Max open positions option next to Prevent Pyramiding.
Why it exists
preventPyramiding blocks a second entry on the same symbol. A strategy that runs on ten coins on one futures account can still open ten positions on the same candle. Every new position uses margin of the whole account, and at a margin ratio of 100 % the exchange liquidates the account.
maxOpenPositions answers the account question instead: how many positions may be open at once, over all symbols.
Enable it
Turn on Max open positions in the trade options of the Trade Command Builder and enter the count, or add one field to the payload:
{
"exchange": "bybit",
"pair": "ETHUSDT",
"apiKey": "bybit-main",
"isBuy": true,
"isMarket": true,
"unitsType": "percentBalance",
"unitsPercent": 20,
"leverage": 5,
"maxOpenPositions": 1,
"token": "YOUR_TOKEN"
}
The value is a whole number of 1 or more. A value of 0 or below is rejected with a message that names the field. Omit the field to turn the check off. The field is read per signal, not stored on your account, so it belongs on every entry alert of the strategy.
How the check works
| Signal | Checked? |
|---|---|
| Futures buy or sell that opens a position | Yes |
| Spot buy | Yes |
| Entry on a symbol that already has a position (an add) | Passes |
Flip with closeCurrentPosition on the same symbol | Passes |
Close, reduceOnly, stop loss, take profit, cancel | Never checked |
| Spot sell | Never checked |
What counts as a position
Futures: every open position on the account in that market, also positions you opened by hand and positions of a bot on the same API key. A long and a short on the same symbol (hedge mode) count as one position. Binance USDⓈ-M and COIN-M are separate wallets, so each counts its own positions. On OKX a swap or futures signal counts the swap and futures positions.
Spot: every coin you hold above the exchange minimum, free and locked in orders together, with these exceptions:
- the quote currency of the alert (USDT for
ETHUSDT); - every coin with "USD" in its name (USDT, USDC, FDUSD, USDe, PYUSD, USD and so on);
- a coin that has no market against the quote currency of the alert.
A leftover below the minimum order size or the minimum order value of the exchange is dust and does not count. Fee tokens like BNB or KCS and long-term holdings above the minimum count like any other coin.
Worked example
"maxOpenPositions": 2 on a strategy that trades five coins on one futures account. All five fire on the same candle.
| # | Signal | Open before | What TVH does | Open after |
|---|---|---|---|---|
| 1 | BTCUSDT long | none | Places the entry | BTCUSDT |
| 2 | ETHUSDT long | BTCUSDT | Places the entry | BTCUSDT, ETHUSDT |
| 3 | SOLUSDT long | BTCUSDT, ETHUSDT | Skips the signal and logs it | BTCUSDT, ETHUSDT |
| 4 | XRPUSDT long | BTCUSDT, ETHUSDT | Skips the signal and logs it | BTCUSDT, ETHUSDT |
| 5 | BTCUSDT add | BTCUSDT, ETHUSDT | Places the add, the symbol is open already | BTCUSDT, ETHUSDT |
Signals of one candle on one account run one after the other for this check, so two entries cannot both see the same free slot. A signal waits at most 60 seconds for its turn. If it does not get it, it is not executed and the reason is logged.
What you see in the Activity Log
| Situation | Log line |
|---|---|
| Limit reached | ETHUSDT Signal ignored: maxOpenPositions is 1 and 1 position is open on the account (XRPUSDT). |
| Positions or balances unreadable | ETHUSDT Signal not executed: the open positions of the account could not be read, so maxOpenPositions cannot be checked (...). |
| Waited 60 s without a turn | ETHUSDT Signal not executed: other signals on this account held the maxOpenPositions lock for 60 s. |
| BitMEX or MT5 | A warning that the field is ignored. The entry goes out without the limit. |
Fail-closed
If the exchange does not return your positions, your balances, a price or the symbol information, TVH does not guess. A failed read never counts as "no positions": the entry is not executed and the reason is logged. Check the account on the exchange, then send the signal again.
Known limits
- Limit entries. A resting limit entry is not a position yet and does not count. Two limit entries on two symbols can both fill.
- Spot leftovers. A rest from an earlier sell that is still above the exchange minimum counts as a position.
- Exchange delay. The count reads the exchange. A position that the exchange shows late after a fill can let a second entry through.
Copy trading
The flag travels with the broadcast, the same way as preventPyramiding. Each follower counts the positions of their own account against the limit. See Broadcast a Signal.
Not supported
- BitMEX: the field is ignored with a warning, the entry goes out without the limit.
- MT5: the field is ignored with a warning, because the server cannot see the positions of your terminal.
Related
- Conditional Logic:
preventPyramidingandconditionalPyramiding, the per-symbol guards. - Max Exposure Multiple: caps the size of one position against your equity.
- Activity Log: where skips show up.