PositionManager#

API documentation for tradeexecutor.strategy.pandas_trader.position_manager.PositionManager Python class in Trading Strategy framework.

class PositionManager[source]#

Bases: object

An utility class to open and close new trade positions.

PositionManager hides away the complex logic reason about trades. It is designed to be used in a trading strategy’s decide_trades() function as an utility class to generate trades a list of TradeExecution objects.

It offers a simple interface for trading for people who are used to TradingView’s Pine Script or similar limited trade scripting environment.

PositionManager helps about

  • How to have up-to-date price information

  • Setting take profit/stop loss parameters for positions

  • Converting between US dollar prices, crypto prices

  • Converting between quantity and value of a trade

  • Caring whether we have an existing position open for the trading pair already

  • Shortcut methods for trading strategies that trade only a single trading pair

PositionManager takes the price feed and current execution state as an input and produces the execution instructions to change positions.

Below are some recipes how to use position manager.

Position manager is usually instiated at your decide_trades function as the following:

from typing import List, Dict

from tradeexecutor.state.visualisation import PlotKind
from tradeexecutor.state.trade import TradeExecution
from tradeexecutor.strategy.pricing_model import PricingModel
from tradeexecutor.strategy.pandas_trader.position_manager import PositionManager
from tradeexecutor.state.state import State
from tradingstrategy.universe import Universe


def decide_trades(
        timestamp: pd.Timestamp,
        universe: Universe,
        state: State,
        pricing_model: PricingModel,
        cycle_debug_data: Dict) -> List[TradeExecution]:

    # Create a position manager helper class that allows us easily to create
    # opening/closing trades for different positions
    position_manager = PositionManager(timestamp, universe, state, pricing_model)

How to check if you have an open position using is_any_open() and then open a new position:

# List of any trades we decide on this cycle.
# Because the strategy is simple, there can be
# only zero (do nothing) or 1 (open or close) trades
# decides
trades = []

if not position_manager.is_any_open():
    buy_amount = cash * position_size
    trades += position_manager.open_1x_long(pair, buy_amount)

return trades

How to check the entry price and open quantity of your latest position. See also decimal.Decimal about arbitrary precision decimal numbers in Python.

# Will throw an exception if there is no position open
current_position = position_manager.get_current_position()

# Quantity is the open amount in tokens.
# This is expressed in Python Decimal class,
# because Ethereum token balances are accurate up to 18 decimals
# and this kind of accuracy cannot be expressed in floating point numbers.
quantity = current_position.get_quantity()
assert quantity == Decimal('0.03045760003971992547285959728')

# The current price is the price of the trading pair
# that was recorded on the last price feed sync.
# This is a 64-bit floating point, as the current price
# is always approximation based on market conditions.
price = current_position.get_current_price()
assert price == 1641.6263899583264

# The opening price is the price of the first trade
# that was made for this position. This is the actual
# executed price of the trade, expressed as floating
# point for the convenience.
price = current_position.get_opening_price()
assert price == 1641.6263899583264
__init__(timestamp, universe, state, pricing_model, default_slippage_tolerance=0.017)[source]#

Create a new PositionManager instance.

Call within decide_trades function.

Parameters:

Methods

__init__(timestamp, universe, state, ...[, ...])

Create a new PositionManager instance.

adjust_position(pair, dollar_delta, ...[, ...])

Adjust holdings for a certain position.

adjust_short(position, new_value[, notes, ...])

Increase/decrease short based on the amount of collateral.

close_all()

Close all open positions.

close_credit_supply_position(position[, ...])

Close a credit supply position

close_position(position[, trade_type, ...])

Close a single position.

close_short(position[, quantity, notes, ...])

Close a short position

close_short_position(position[, quantity, ...])

Legacy.

close_spot_position(position[, trade_type, ...])

Close a single spot market trading position.

estimate_asset_quantity(pair, dollar_amount)

Convert dollar amount to the quantity of a token.

get_current_credit_supply_position()

Get the current single credit supply position.

get_current_long_position()

Get the current single long position.

get_current_portfolio()

Return the active portfolio of the strategy.

get_current_position()

Get the current single position.

get_current_position_for_pair(pair)

Get the current open position for a specific trading pair.

get_current_short_position()

Get the current single short position.

get_last_closed_position()

Get the position that was last closed.

get_pair_fee([pair])

Estimate the trading/LP fees for a trading pair.

get_trading_pair(pair_id)

Get a trading pair identifier by its internal id.

is_any_credit_supply_position_open()

Do we have any credit supply positions open.

is_any_long_position_open()

Do we have any long positions open.

is_any_open()

Do we have any positions open.

is_any_short_position_open()

Do we have any short positions open.

open_1x_long(pair, value[, take_profit_pct, ...])

Open a long.

open_credit_supply_position_for_reserves(amount)

Move reserve currency to a credit supply position.

open_short(pair, value, *[, leverage, ...])

Open a short position.

update_stop_loss(position, stop_loss)

Update the stop loss for the current position.
__init__(timestamp, universe, state, pricing_model, default_slippage_tolerance=0.017)[source]#

Create a new PositionManager instance.

Call within decide_trades function.

Parameters:
is_any_open()[source]#

Do we have any positions open.

See also

Return type:

bool

is_any_long_position_open()[source]#

Do we have any long positions open.

See also

Return type:

bool

is_any_short_position_open()[source]#

Do we have any short positions open.

See also

Return type:

bool

is_any_credit_supply_position_open()[source]#

Do we have any credit supply positions open.

See also

Return type:

bool

get_current_position()[source]#

Get the current single position.

This is a shortcut function for trading strategies that operate only a single trading pair and a single position.

See also

Returns:

Currently open trading position

Raises:

NoSingleOpenPositionError – If you do not have a position open or there are multiple positions open.

Return type:

TradingPosition

get_current_long_position()[source]#

Get the current single long position.

This is a shortcut function for trading strategies that operate only a single trading pair and a single long position.

See also

Returns:

Currently open long trading position

Raises:

NoSingleOpenPositionError – If you do not have a position open or there are multiple positions open.

get_current_short_position()[source]#

Get the current single short position.

This is a shortcut function for trading strategies that operate only a single trading pair and a single short position.

If you have multiple short positions open use get_current_position_for_pair() to distinguish between them.

# aave_usdc is an instance of TradingPairIdentifier
aave_shorting_pair = strategy_universe.get_shorting_pair(aave_usdc)
aave_short_position = position_manager.get_current_position_for_pair(aave_shorting_pair)

See also

Returns:

Currently open short trading position

Raises:

NoSingleOpenPositionError – If you do not have a position open or there are multiple positions open.

get_current_credit_supply_position()[source]#

Get the current single credit supply position.

This is a shortcut function for trading strategies that operate only a single trading pair and a single credit supply position.

See also

Returns:

Currently open credit supply trading position

Raises:

NoSingleOpenPositionError – If you do not have a position open or there are multiple positions open.

get_current_position_for_pair(pair)[source]#

Get the current open position for a specific trading pair.

Returns:

Currently open trading position.

If there is no open position return None.

Parameters:

pair (TradingPairIdentifier) –

Return type:

Optional[TradingPosition]

get_last_closed_position()[source]#

Get the position that was last closed.

If multiple positions are closed at the same time, return a random position.

Example:

last_position = position_manager.get_last_closed_position()
if last_position:
    ago = timestamp - last_position.closed_at
    print(f"Last position was closed {ago}")
else:
    print("Strategy has not decided any position before")
Returns:

None if the strategy has not closed any positions

Return type:

Optional[TradingPosition]

get_current_portfolio()[source]#

Return the active portfolio of the strategy.

Return type:

Portfolio

get_trading_pair(pair_id)[source]#

Get a trading pair identifier by its internal id.

Note that internal integer ids are not stable over multiple trade cycles and might be reset. Always use (chain id, smart contract) for persistent pair identifier.

Returns:

Trading pair information

Parameters:

pair_id (int) –

Return type:

TradingPairIdentifier

get_pair_fee(pair=None)[source]#

Estimate the trading/LP fees for a trading pair.

This information can come either from the exchange itself (Uni v2 compatibles), or from the trading pair (Uni v3).

The return value is used to fill the fee values for any newly opened trades.

Parameters:

pair (Optional[TradingPairIdentifier]) –

Trading pair for which we want to have the fee.

Can be left empty if the underlying exchange is always offering the same fee.

Returns:

The estimated trading fee, expressed as %.

Returns None if the fee information is not available. This can be different from zero fees.

Return type:

Optional[float]

open_1x_long(pair, value, take_profit_pct=None, stop_loss_pct=None, trailing_stop_loss_pct=None, stop_loss_usd=None, notes=None, slippage_tolerance=None)[source]#

Open a long.

  • For simple buy and hold trades

  • Open a spot market buy.

  • Checks that there is not existing position - cannot increase position

See also

Parameters:

  • pair (Union[DEXPair, TradingPairIdentifier]) – Trading pair where we take the position

  • value (float | decimal.Decimal) – How large position to open, in US dollar terms

  • take_profit_pct (Optional[float]) – If set, set the position take profit relative to the current market price. 1.0 is the current market price. If asset opening price is $1000, take_profit_pct=1.05 will sell the asset when price reaches $1050.

  • stop_loss_pct (Optional[float]) – If set, set the position to trigger stop loss relative to the current market price. 1.0 is the current market price. If asset opening price is $1000, stop_loss_pct=0.95 will sell the asset when price reaches 950.

  • trailing_stop_loss_pct (Optional[float]) – If set, set the position to trigger trailing stop loss relative to the current market price. Cannot be used with stop_loss_pct or stop_loss_usd.

  • stop_loss_usd (Optional[float]) – If set, set the position to trigger stop loss at the given dollar price. Cannot be used with stop_loss_pct or trailing_stop_loss_pct.

  • notes (Optional[str]) – Human readable notes for this trade

  • slippage_tolerance (Optional[float]) –

    Slippage tolerance for this trade.

    Use default_slippage_tolerance if not set.

Returns:

A list of new trades. Opening a position may general several trades for complex DeFi positions, though usually the result contains only a single trade.

Return type:

List[TradeExecution]

adjust_position(pair, dollar_delta, quantity_delta, weight, stop_loss=None, take_profit=None, trailing_stop_loss=None, slippage_tolerance=None, override_stop_loss=False, notes=None)[source]#

Adjust holdings for a certain position.

Used to rebalance positions.

This method rarely needs to be called directly, but is usually part of portfolio construction strategy that is using tradeexecutor.strategy.alpha_model.AlphaModel.

A new position is opened if no existing position is open. If everything is sold, the old position is closed

If the rebalance is sell (dollar_amount_delta is negative), then calculate the quantity of the asset to sell based on the latest available market price on the position.

Warning

Adjust position cannot be used to close an existing position, because epsilons in quantity math. Use close_position() for this.

Parameters:

  • pair (TradingPairIdentifier) – Trading pair which position we adjust

  • dollar_delta (float) –

    How much we want to increase/decrease the position in US dollar terms.

    TODO: If you are selling the assets, you need to calculate the expected dollar estimate yourself at the moment.

  • quantity_delta (Optional[float]) –

    How much we want to increase/decrease the position in the asset unit terms.

    Used only when decreasing existing positions (selling). Set to None if not selling.

  • weight (float) –

    What is the weight of the asset in the new target portfolio 0….1. Currently only used to detect condition “sell all” instead of trying to match quantity/price conversion.

    If unsure and buying, set to 1.

  • stop_loss (Optional[float]) –

    Set the stop loss for the position.

    Use 0…1 based on the current mid price. E.g. 0.98 = 2% stop loss under the current mid price.

    Sets the initial stop loss. If you want to override this for an existing position you need to use override_stop_loss parameter.

  • take_profit (Optional[float]) –

    Set the take profit for the position.

    Use 0…1 based on the current mid price. E.g. 1.02 = 2% take profit over the current mid-price.

  • slippage_tolerance (Optional[float]) –

    Slippage tolerance for this trade.

    Use default_slippage_tolerance if not set.

  • override_stop_loss – If not set and a position has already stop loss set, do not modify it.

  • notes (Optional[str]) –

    Human-readable plain text notes on the trade.

    Used for diagnostics.

  • trailing_stop_loss (Optional[float]) –

Returns:

List of trades to be executed to get to the desired position level.

Return type:

List[TradeExecution]

close_spot_position(position, trade_type=TradeType.rebalance, notes=None, slippage_tolerance=None)[source]#

Close a single spot market trading position.

See close_position() for usage.

Parameters:
Return type:

List[TradeExecution]

close_credit_supply_position(position, quantity=None, notes=None, trade_type=TradeType.rebalance)[source]#

Close a credit supply position

Parameters:
Returns:

New trades to be executed

Return type:

List[TradeExecution]

close_position(position, trade_type=None, notes=None, slippage_tolerance=None)[source]#

Close a single position.

The position may already have piled up selling trades. In this case calling close_position() again on the same position does nothing and None is returned.

Parameters:

  • position (TradingPosition) – Position to be closed

  • trade_type (Optional[TradeType]) – What’s the reason to close the position

  • notes (Optional[str]) – Human-readable notes for this trade

  • slippage_tolerance (Optional[float]) –

    Slippage tolerance for this trade.

    Use default_slippage_tolerance if not set.

Returns:

Get list of trades needed to close this position.

return list of trades.

Return type:

List[TradeExecution]

close_all()[source]#

Close all open positions.

Returns:

List of trades that will close existing positions

Return type:

List[TradeExecution]

estimate_asset_quantity(pair, dollar_amount)[source]#

Convert dollar amount to the quantity of a token.

Use the market mid-price of the timestamp.

Parameters:

  • pair (TradingPairIdentifier) – Trading pair of which base pair we estimate.

  • dollar_amount (float) – Get the asset quantity for this many dollars.

Returns:

Asset quantity.

The sign of the asset quantity is the same as the sign of dollar_amount parameter.

We return as float, because the exact quantity is never known due the price fluctuations and slippage.

Return type:

float

update_stop_loss(position, stop_loss)[source]#

Update the stop loss for the current position.

Parameters:

  • position (TradingPosition) – Position to update. For multipair strategies, providing this parameter is strongly recommended.

  • stop_loss (float) – Stop loss in US dollar terms

  • mid_price – Mid price of the pair (https://tradingstrategy.ai/glossary/mid-price). Provide when possible for most complete statistical analysis. In certain cases, it may not be easily available, so it’s optional.

open_credit_supply_position_for_reserves(amount)[source]#

Move reserve currency to a credit supply position.

Parameters:

amount (float) – Amount of cash to lend out

Returns:

List of trades that will open this credit position

Return type:

List[TradeExecution]

open_short(pair, value, *, leverage=1.0, take_profit_pct=None, stop_loss_pct=None, trailing_stop_loss_pct=None, notes=None)[source]#

Open a short position.

NOTE: take_profit_pct and stop_loss_pct are more related to capital at risk percentage than to the price. So this will likely be changed in the future.

Parameters:

  • pair (Union[DEXPair, TradingPairIdentifier]) – Trading pair where we take the position

  • value (float) –

    How much cash reserves we allocate to open this position.

    In US dollars.

    For example to open 2x short where we allocate $1000 from our reserves, this value is $1000.

  • leverage (float) – Leverage level to use for the short position

  • take_profit_pct (Optional[float]) – If set, set the position take profit relative to the current market price. 1.0 is the current market price. If asset opening price is $1000, take_profit_pct=1.05 will buy back the asset when price reaches $950.

  • stop_loss_pct (Optional[float]) – If set, set the position to trigger stop loss relative to the current market price. 1.0 is the current market price. If asset opening price is $1000, stop_loss_pct=0.98 will buy back the asset when price reaches $1020.

  • trailing_stop_loss_pct (Optional[float]) – If set, set the position to trigger trailing stop loss relative to the current market price. Cannot be used with stop_loss_pct.

  • notes (Optional[str]) –

Returns:

List of trades that will open this credit position

Return type:

list[tradeexecutor.state.trade.TradeExecution]

close_short_position(position, quantity=None, notes=None, trade_type=TradeType.rebalance)[source]#

Legacy.

Use close_short().

Parameters:
Return type:

List[TradeExecution]

close_short(position, quantity=None, notes=None, trade_type=TradeType.rebalance)[source]#

Close a short position

  • Buy back the shorted token

  • Release collateral and return it as cash to the reserves

  • Move any gained interest back to the reserves as well

Parameters:
Returns:

New trades to be executed

Return type:

List[TradeExecution]

adjust_short(position, new_value, notes=None, trade_type=TradeType.rebalance, minimum_rebalance_trade_threshold=0.0)[source]#

Increase/decrease short based on the amount of collateral.

Short adjust used in alpha model.

  • Short is already open

  • The amount of short is changing

  • We want to maintain the existing leverage

  • Any excess collateral is returned to cash reserves, any new collateral is moved for the cash reserves to the short

  • Cannot be used to open/close position

See also

Parameters:

  • position (TradingPosition) –

    Position to close.

    Must be a short position.

  • new_value (float) –

    The allocated collateral for this position after the trade in US Dollar reserves.

    The absolute amunt of reserve currency we will use for this short.

  • quantity –

    How much of the quantity we reduce.

    If not given close the full position.

  • price – The spot price of the underlying pair.

  • notes (Optional[str]) –

  • trade_type (TradeType) –

  • minimum_rebalance_trade_threshold (float) –

Returns:

New trades to be executed

Return type:

List[TradeExecution]