Learning / Syntax / position()

position - Set a Target at Market

Specify where you want to end up, not what to trade. Flipr.Cloud calculates the buy/sell direction and amount automatically.

What is Position Targeting?

Position targeting is a powerful abstraction that lets you think in terms of desired outcomes rather than individual trades. Instead of manually calculating "I need to buy X to reach Y position", you simply state your target position and Flipr.Cloud calculates the market orders needed to reach it.

Positive values = long position targets
Negative values = short position targets
Zero = close position completely
The system automatically determines whether to buy, sell, or flip your position

How It Works

Flipr.Cloud compares your current position to your target position and calculates the required trade:

Current Position	Target Position	Action Taken
0 BTC	`pos 0.5`	Buy 0.5 BTC
0.3 BTC long	`pos 0.8`	Buy 0.5 BTC (increase position)
0.8 BTC long	`pos 0.3`	Sell 0.5 BTC (reduce position)
0.5 BTC long	`pos 0`	Sell 0.5 BTC (close position)
0.5 BTC long	`pos -0.5`	Sell 1.0 BTC (flip to short)
-0.3 BTC short	`pos -0.8`	Sell 0.5 BTC (increase short)

The math is handled automatically. You never need to calculate buy/sell direction or amounts manually.

%p Behavior Reference

The sign in %p indicates the target direction, not a flip. Positive = long target, negative = short target. Targets of 100%p and -100%p leave an existing position of the matching direction unchanged. Other percentages are recalculated each time: repeating 50%p halves the current size again.

Case	From	Command	Result
1	LONG	`pos -100%p`	Sell 2x size → SHORT
2	SHORT	`pos -100%p`	Skipped (idempotent)
3	SHORT	`pos -100%p`	Skipped (confirmed)
4	SHORT	`pos 100%p`	Buy 2x size → LONG
5	LONG	`pos 100%p`	Skipped (idempotent)
6	LONG	`pos 50%p`	Sell 0.5x, stays LONG (reduceOnly)
7	SHORT	`pos 50%p`	Buy 1.5x → LONG 0.5x (flip+reduce)
8	LONG	`pos -50%p`	Sell 1.5x → SHORT 0.5x (flip+reduce)
9	SHORT	`pos -50%p`	Buy 0.5x, stays SHORT (reduceOnly)
10	SHORT	`pos 0`	Closed

Syntax

pos <amount>
position <amount>
target <amount>

All three aliases work identically. Use whichever feels most natural.

Parameters

amountRequired

Type: number or string

The target position size you want to achieve. Can be specified in several notations:

Format	Description	Example
`0.01`	Fixed quantity (long)	Target 0.01 BTC long
`-0.01`	Fixed quantity (short)	Target 0.01 BTC short
`50%`	% of total balance	Position worth 50% of balance
`-50%`	% of total balance (short)	Short position worth 50% of balance
`50%%` or `50%a`	% of available balance	Position using 50% of free balance
`50%p`	Target long, 50% of current size	If position is 1.0, target becomes +0.5 (long)
`-50%p`	Target short, 50% of current size	If position is 1.0, target becomes -0.5 (short)
`-100%p`	Target short, same size as current	If position is 1.0, target becomes -1.0 (short). Idempotent: if already short, no action.
`0`	Close position	Close the position for this block’s symbol and API key

Sign matters: Positive = long target, Negative = short target, Zero = close

No inline parameters: Unlike market and limit, the pos command only accepts a target amount. It does not support inline sl, tp, margin, or reduce parameters. If you need entry with protections in a single command, use market instead.

Examples

Example 1: Target 90% Long Position

BTCUSDT on My_API_Key
pos 90%

Targets a long position worth 90% of your total account balance. If you currently have 0 position, it buys. If you're already long 50%, it adds more. If you're long 100%, it reduces to 90%.

Example 2: Target 80% Short Position

ETHUSDT on My_API_Key
pos -80%

Targets a short position worth 80% of your balance. The negative sign indicates short. Flipr.Cloud will close any long position first, then open the short position to reach the target.

Example 3: Close Position Completely

BTCUSDT on My_API_Key
pos 0

Closes your entire position regardless of size or direction. Equivalent to close all, scoped to the symbol and API key in this block.

Example 4: Flip Position from Long to Short

ETHUSDT on My_API_Key
// Assuming you're currently long 0.5 ETH
pos -100%p

This example uses -100%p which means "target short with same size as current position". The sign indicates the direction: negative = short target. If you're long 0.5 ETH, this becomes a target of -0.5 ETH. The position change is executed at market, without a price trigger. If you're already short, this command has no effect (idempotent).

Example 5: Reduce Position by 50%

BTCUSDT on My_API_Key
// Assuming you're currently long 1.0 BTC
pos 50%p

Targets 50% of your current position size. If you're long 1.0 BTC, this sets target to 0.5 BTC long, automatically selling 0.5 BTC to reach the target.

Example 6: Increase Position by Doubling

ETHUSDT on My_API_Key
// Assuming you're currently long 0.3 ETH
pos 200%p

Targets 200% of current position size (double it). If you're long 0.3 ETH, this sets target to 0.6 ETH, buying an additional 0.3 ETH at market. Repeating the command doubles the new size again.

Example 7: Reduce an Existing Short at Market

BTCUSDT on My_API_Key
// Assuming you are short 0.2 BTC
pos -50%p

Targets a short position of 0.1 BTC, buying 0.1 BTC at market to reduce the existing short. The minus sign preserves the short target; pos 50%p would target a long position instead.

Close All or One Position Side

Each command applies only to the symbol and API key in its header. Choose one of these alternatives:

Command	Effect at market
`close all`	Close the position, including both sides in hedge mode; equivalent to `pos 0`.
`close long`	Close the long side with a sell, leaving any short side intact.
`close short`	Close the short side with a buy, leaving any long side intact.

In one-way mode, a side-specific close acts only when the position matches that side. If that side is absent, it is skipped. These commands close positions; use the Cancel guide for pending orders.

Best Practices

When to Use Position Targeting

When you want to think in terms of portfolio allocation (e.g., "I want 70% long BTC")
When you don't know your current position size and want to reach a specific target
When building automated strategies that should maintain specific exposure levels
When you need to flip positions based on signals without manual calculation

Percentage Notations Explained

Understanding the different percentage notations:

50% / -50% - % of balance. Sign = direction (+ long, - short)
50%% or 50%a - % of available balance only
50%p - Target long, 50% of current position size
-50%p - Target short, 50% of current position size. Sign = direction, not flip.

Targets and Limit Orders

pos is a market target command. To place an order at a specified price, use limit with a side, quantity and price. A limit order trades that quantity; it does not calculate a desired final position.

Safety Considerations

Always verify your target sign (positive = long, negative = short)
Be cautious with -100%p on volatile markets — if you're long, it will close and reopen short at market price
Market targets can incur slippage; limit orders require a separately chosen side, quantity and price, and may remain unfilled
Test with small amounts first when using percentage-based position targeting

Related Commands

market - Execute position changes immediately at market price

limit - Set conditional position changes at specific price levels

balance - Check your current balance and position sizes