fractal.core.entities package

Subpackages

fractal.core.entities.models package

Submodules

fractal.core.entities.aave module

class fractal.core.entities.aave.AaveEntity(*args, max_ltv: float = 0.8, liq_thr: float = 0.85, **kwargs)[source]

Bases: BaseLendingEntity

Represents an Aave isolated market entity.

action_borrow(amount_in_product: float)[source]

Borrows an amount on the Aave protocol.

Parameters:: amount_in_product (float, optional) – The amount to borrow in product value.

action_deposit(amount_in_notional: float) → None[source]

Deposits the specified amount in notional value into the entity. Each entity stores the cash balance in notional value.

Parameters:: amount_in_notional (float) – The amount to be deposited in notional value.

action_redeem(amount_in_product: float)[source]

Redeems an amount on the Aave protocol.

Parameters:: amount_in_product (float, optional) – The amount to redeem in product value.

action_withdraw(amount_in_notional: float) → None[source]

Withdraws the specified amount from the entity’s account. Each entity stores the cash balance in notional value.

Parameters:: amount_in_notional (float) – The amount to withdraw in notional value.

property balance: float

Calculates the balance of the Aave entity.

Aave entity balance is calculated as the difference between the collateral and the borrowed amount.

Returns:: The balance of the Aave entity.
Return type:: float

calculate_repay(target_ltv: float) → float[source]

Calculates the amount to repay in order to reach the target loan-to-value ratio.

Parameters:: target_ltv (float) – The target loan-to-value ratio.
Returns:: The amount to repay in product value.
Return type:: float

check_liquidation()[source]

Checks if the entity is eligible for liquidation.

Liquidation occurs when the LTV ratio exceeds the liquidation threshold.

property ltv: float

Calculates the loan-to-value (LTV) ratio of the Aave entity.

LTV ratio is calculated as the ratio of the borrowed amount to the collateral.

Returns:: The LTV ratio.
Return type:: float

update_state(state: AaveGlobalState)[source]

class fractal.core.entities.aave.AaveGlobalState(notional_price: float = 0.0, product_price: float = 0.0, lending_rate: float = 0.0, borrowing_rate: float = 0.0)[source]

Bases: object

Represents the global state of the Aave protocol.

notional_price

The notional price.

Type:: float

product_price

The product price.

Type:: float

lending_rate

The lending rate.

Type:: float

borrowing_rate

The borrowing rate.

Type:: float

borrowing_rate: float = 0.0

lending_rate: float = 0.0

notional_price: float = 0.0

product_price: float = 0.0

class fractal.core.entities.aave.AaveInternalState(collateral: float = 0.0, borrowed: float = 0.0)[source]

Bases: object

Represents the internal state of an Aave entity.

collateral

The amount of collateral in notional.

Type:: float

borrowed

The amount borrowed in product.

Type:: float

borrowed: float = 0.0

collateral: float = 0.0

fractal.core.entities.gmx_v2 module

class fractal.core.entities.gmx_v2.GMXV2Entity(*args, trading_fee: float = 0.001, liquidation_leverage: float = 100, **kwargs)[source]

Bases: BaseHedgeEntity

Represents a GMX isolated market entity.

action_deposit(amount_in_notional: float)[source]

Deposits a specified amount of notional into the entity’s collateral.

Parameters:: amount_in_notional (float) – The amount of notional to deposit.

action_open_position(amount_in_product: float)[source]

Opens a position with a specified amount of product.

Parameters:: amount_in_product (float) – The amount of product to open the position with.

action_withdraw(amount_in_notional: float) → float[source]

Withdraws a specified amount of notional from the entity’s collateral.

Parameters:: amount_in_notional (float) – The amount of notional to withdraw.
Returns:: The remaining balance after the withdrawal.
Return type:: float
Raises:: ValueError – If there is not enough balance to withdraw.

property balance

Calculates the current balance of the entity.

Balance is a sum of the collateral and the PNL. :returns: The current balance. :rtype: float

property leverage

Calculates the leverage of the entity.

The leverage is the absolute ratio of the total position size to the balance. :returns: The leverage. :rtype: float

property pnl: float

Calculates the total profit and loss (PNL) of all positions.

PNL is a sum of PNLs of all positions. :returns: The total PNL. :rtype: float

property size

Calculates the total size of all positions.

Size is a sum of all position amounts. :returns: The total size. :rtype: float

update_state(state: GMXV2GlobalState, *args, **kwargs) → None[source]

Updates the entity’s state with the given global state.

Updates the global state.
Check liquidation.
Settle fundings and borrowings.

Parameters:: state (GMXGlobalState) – The global state to update with.

exception fractal.core.entities.gmx_v2.GMXV2EntityException[source]

Bases: EntityException

Exception raised for errors in the GMX V2 entity.

class fractal.core.entities.gmx_v2.GMXV2GlobalState(price: float = 0.0, funding_rate_short: float = 0.0, funding_rate_long: float = 0.0, borrowing_rate_short: float = 0.0, borrowing_rate_long: float = 0.0, longs_pay_shorts: bool = True)[source]

Bases: GlobalState

Represents the global state of the GMX V2 entity.

GMX V2 has two-sided funding rates and borrowing rates.

price: float - The current price of the product. funding_rate_short: float - The short funding rate. funding_rate_long: float - The long funding rate. borrowing_rate_short: float - The short borrowing rate. borrowing_rate_long: float - The long borrowing rate. longs_pay_shorts: bool - Whether longs pay shorts.

borrowing_rate_long: float = 0.0

borrowing_rate_short: float = 0.0

funding_rate_long: float = 0.0

funding_rate_short: float = 0.0

longs_pay_shorts: bool = True

price: float = 0.0

class fractal.core.entities.gmx_v2.GMXV2InternalState(collateral: float = 0.0, positions: ~typing.List[~fractal.core.entities.gmx_v2.GMXV2Position] = <factory>)[source]

Bases: InternalState

Represents the internal state of the GMX V2 entity.

It includes the collateral and the positions of the entity.

collateral: float = 0.0

positions: List[GMXV2Position]

class fractal.core.entities.gmx_v2.GMXV2Position(amount: float, entry_price: float)[source]

Bases: object

A position in the GMXHedge. It includes the amount and the entry price of the position.

pnl(price: float) → float[source]

Calculates the profit and loss (PNL) of the position.

PNL = Amount * (Price - Entry Price)

fractal.core.entities.hedge module

class fractal.core.entities.hedge.BaseHedgeEntity[source]

Bases: BaseEntity

Base class for Hedge entities.

Hedge entities are entities that can open positions on the exchange.

abstract action_open_position(amount_in_product: float)[source]

Opens a position on the protocol.

Parameters:: amount_in_product (float, optional) – The amount to open in product value.

abstract property leverage: float

Returns the leverage of the entity.

Returns:: The leverage of the entity.
Return type:: float

abstract property size: float

Returns the size of the entity.

Returns:: The size of the entity.
Return type:: float

fractal.core.entities.lending module

class fractal.core.entities.lending.BaseLendingEntity[source]

Bases: BaseEntity

Base class for Lending entities.

Lending entities are entities that can lend and borrow on the protocol.

abstract action_borrow(amount_in_product: float)[source]

Borrows an amount on the protocol.

Parameters:: amount_in_product (float, optional) – The amount to borrow in product value.

abstract action_redeem(amount_in_product: float)[source]

Redeems an amount on the protocol.

Parameters:: amount_in_product (float, optional) – The amount to redeem in product value.

fractal.core.entities.pool module

class fractal.core.entities.pool.BasePoolEntity[source]

Bases: BaseEntity

Base class for Pool entity.

Pool entity is responsible for managing the position in the pool. It can open and close the position in the pool.

abstract action_close_position()[source]: Close position in pool.

abstract action_open_position(amount_in_notional: float, *args, **kwargs)[source]

Open position in pool.

Parameters:: amount_in_notional (float) – amount in notional

fractal.core.entities.spot module

class fractal.core.entities.spot.BaseSpotEntity[source]

Bases: BaseEntity

Base class for Spot entity.

Spot entity is responsible for managing the position in the spot market. We can buy and sell the product in the spot market.

abstract action_buy(amount_in_notional: float)[source]

Executes a buy action on the protocol.

Parameters:: amount_in_notional (float, optional) – The amount to buy in notional value.
Raises:: EntityException – If there is not enough cash to buy.

abstract action_sell(amount_in_product: float)[source]

Executes a sell action on the protocol.

Parameters:: amount_in_product (float, optional) – The amount to sell in product value.
Raises:: EntityException – If there is not enough product to sell.

fractal.core.entities.steth module

class fractal.core.entities.steth.StakedETHEntity(*args, trading_fee: float = 0.003, **kwargs)[source]

Bases: BaseSpotEntity

Represents an entity for trading on the StakedETH token. This is a simple entity that can buy, sell, deposit, and withdraw stETH. Also this entity control staking rate.

action_buy(amount_in_notional: float)[source]

Executes a buy action on the StakedETH protocol.

Parameters:: amount_in_notional (float, optional) – The amount to buy in notional value.
Raises:: ValueError – If there is not enough cash to buy.

action_deposit(amount_in_notional: float)[source]

Executes a deposit action on the StakedETH protocol.

Parameters:: amount_in_notional (float) – The amount to deposit in notional value.

action_sell(amount_in_product: float)[source]

Executes a sell action on the StakedETH protocol.

Parameters:: amount_in_product (float, optional) – The amount to sell in product value.
Raises:: ValueError – If there is not enough product to sell.

action_withdraw(amount_in_notional: float)[source]

Executes a withdraw action on the StakedETH protocol.

Parameters:: amount_in_notional (float, optional) – The amount to withdraw in notional value.
Raises:: ValueError – If there is not enough cash to withdraw.

property balance: float

Calculates the balance of the StakedETH entity.

The balance is calculated as the sum of the amount of stETH and the cash balance. :returns: The balance of the entity. :rtype: float

update_state(state: StakedETHGlobalState, *args, **kwargs) → None[source]

Updates the global state of the StakedETH protocol. 1. Updates the global state. 2. Add staking rewards to the internal state.

Parameters:: state (StakedETHGlobalState) – The new global state.

exception fractal.core.entities.steth.StakedETHEntityException[source]

Bases: EntityException

Represents an exception for the StakedETH entity.

class fractal.core.entities.steth.StakedETHGlobalState(price: float = 0.0, rate: float = 0.0)[source]

Bases: GlobalState

Represents the global state of any LST ETH token.

price

The price of the stETH.

Type:: float

rate

The rate of the .

Type:: float

price: float = 0.0

rate: float = 0.0

class fractal.core.entities.steth.StakedETHInternalState(amount: float = 0.0, cash: float = 0.0)[source]

Bases: InternalState

Represents the internal state of the StakedETH entity.

amount

The stored amount of stETH.

Type:: float

cash

The amount of cash in notional.

Type:: float

amount: float = 0.0

cash: float = 0.0

fractal.core.entities.uniswap_v2_lp module

class fractal.core.entities.uniswap_v2_lp.UniswapV2LPConfig(fees_rate: float = 0.005, token0_decimals: int = 18, token1_decimals: int = 18, trading_fee: float = 0.003)[source]

Bases: object

Represents the configuration of an UniswapV2 LP entity.

fees_rate

The fees rate.

Type:: float

token0_decimals

The token0 decimals.

Type:: int

token1_decimals

The token1 decimals.

Type:: int

trading_fee

The trading fee.

Type:: float

fees_rate: float = 0.005

token0_decimals: int = 18

token1_decimals: int = 18

trading_fee: float = 0.003

class fractal.core.entities.uniswap_v2_lp.UniswapV2LPEntity(config: UniswapV2LPConfig, *args, **kwargs)[source]

Bases: BasePoolEntity

Represents an Uniswap V2-like LP entity.

It maintains exact 50-50 position of token0 and token1 in the pool.

action_close_position()[source]: Close the position in the LP entity.

action_deposit(amount_in_notional: float) → None[source]

Deposit funds into the LP entity.

Parameters:: amount_in_notional (float) – The amount to deposit.

action_open_position(amount_in_notional: float) → None[source]

Open a position in the LP entity.

Parameters:: amount_in_notional (float) – The amount to invest.

action_withdraw(amount_in_notional: float) → None[source]

Withdraw funds from the LP entity.

Parameters:: amount_in_notional (float) – The amount to withdraw.

property balance: float

Returns the balance of the LP entity.

Returns:: The balance of the LP entity.
Return type:: float

calculate_fees() → float[source]: Calculate fees for position :returns: acc fees for position :rtype: float

update_state(state: UniswapV2LPGlobalState) → None[source]

Update the state of the LP entity.

Update the global state.

2. Update token0 and token1 amounts following AMM formula. :param state: The state of the pool. :type state: UniswapV2LPGlobalState

class fractal.core.entities.uniswap_v2_lp.UniswapV2LPGlobalState(tvl: float = 0.0, volume: float = 0.0, fees: float = 0.0, liquidity: float = 0.0, price: float = 0.0)[source]

Bases: object

Represents the global state of the UniswapV2 LP entity.

tvl

The total value locked.

Type:: float

volume

The trading volume.

Type:: float

fees

The trading fees.

Type:: float

liquidity

The pool liquidity.

Type:: float

price

The pool price [token1 / token0].

Type:: float

fees: float = 0.0

liquidity: float = 0.0

price: float = 0.0

tvl: float = 0.0

volume: float = 0.0

class fractal.core.entities.uniswap_v2_lp.UniswapV2LPInternalState(token0_amount: float = 0.0, token1_amount: float = 0.0, price_init: float = 0.0, liquidity: float = 0.0, cash: float = 0.0)[source]

Bases: object

Represents the internal state of an UniswapV2 LP entity.

token0_amount

The amount of token0.

Type:: float

token1_amount

The amount of token1.

Type:: float

price_init

The position initial price.

Type:: float

liquidity

The position liquidity.

Type:: float

cash

The cash balance.

Type:: float

cash: float = 0.0

liquidity: float = 0.0

price_init: float = 0.0

token0_amount: float = 0.0

token1_amount: float = 0.0

fractal.core.entities.uniswap_v3_lp module

class fractal.core.entities.uniswap_v3_lp.UniswapV3LPConfig(fees_rate: float = 0.005, token0_decimals: int = 18, token1_decimals: int = 18, trading_fee: float = 0.003)[source]

Bases: object

Represents the configuration of an UniswapV3 LP entity.

fees_rate

The fees rate.

Type:: float

token0_decimals

The token0 decimals.

Type:: int

token1_decimals

The token1 decimals.

Type:: int

trading_fee

The trading fee.

Type:: float

fees_rate: float = 0.005

token0_decimals: int = 18

token1_decimals: int = 18

trading_fee: float = 0.003

class fractal.core.entities.uniswap_v3_lp.UniswapV3LPEntity(config: UniswapV3LPConfig, *args, **kwargs)[source]

Bases: BasePoolEntity

Represents an Uniswap V3 LP entity.

It maintains single position in the V3 pool.

action_close_position()[source]: Close the position in the LP entity.

action_deposit(amount_in_notional: float) → None[source]

Deposit funds into the LP entity.

Parameters:: amount_in_notional (float) – The amount to deposit.

action_open_position(amount_in_notional: float, price_lower: float, price_upper: float) → None[source]

Open a position in the LP entity.

Parameters:

amount_in_notional (float) – The amount to invest.
price_lower (float) – The lower price of the range.
price_upper (float) – The upper price of the range.

action_withdraw(amount_in_notional: float) → None[source]

Withdraw funds from the LP entity.

Parameters:: amount_in_notional (float) – The amount to withdraw.

property balance: float

Returns the balance of the LP entity.

Returns:: The balance of the LP entity.
Return type:: float

calculate_fees() → float[source]

Parameters:

position (UniswapV3Position) – position to which calc fees
pool_state (PoolState) – pool state

Returns:

acc fees for position

Return type:

float

calculate_position(deposit_amount: float, price_current: float, price_lower: float, price_upper: float) → str[source]

Add position to positions dict

Parameters:

deposit_amount (float) – deposited token amount in token1
price_current (float) – token1/token0 price
price_upper (float) – upper price bound
price_lower (float) – lower price bound

Returns:

id of position

Return type:

id (str)

calculate_position_from_notional(deposit_amount_in_notional: float, price_current: float, price_lower: float, price_upper: float) → str[source]

Add a new position by notional amount. !Notional amount is the amount of token1!

Parameters:

deposit_amount_in_notional (float) – deposited token amount in token1
price_current (float) – token1/token0 price
price_upper (float) – upper price bound
price_lower (float) – lower price bound

Returns:

id of position

Return type:

id (str)

get_desired_token0_amount(deposit_amount: float, price_current: float, price_lower: float, price_upper: float) → float[source]

Returns desired token0 amount for position

Parameters:

deposit_amount (float) – deposited token amount in token1
price_current (float) – token1/token0 price
price_upper (float) – upper price bound
price_lower (float) – lower price bound

Returns:

desired token0 amount for position

Return type:

desired_token0_amount (float)

price_to_tick(price: float) → float[source]

tick_to_price(tick: float) → float[source]

update_state(state: UniswapV3LPGlobalState) → None[source]

Update the state of the LP entity.

Update the global state.
Update token0 and token1 amounts following Uniswap V3 formula.
Calculate fees and add to cash balance.

Parameters:: state (UniswapV3LPGlobalState) – The state of the pool.

class fractal.core.entities.uniswap_v3_lp.UniswapV3LPGlobalState(tvl: float = 0.0, volume: float = 0.0, fees: float = 0.0, liquidity: float = 0.0, price: float = 0.0)[source]

Bases: object

Represents the global state of the UniswapV3 LP entity.

tvl

The total value locked.

Type:: float

volume

The trading volume.

Type:: float

fees

The trading fees.

Type:: float

liquidity

The pool liquidity.

Type:: float

price

The pool price [token1 / token0].

Type:: float

fees: float = 0.0

liquidity: float = 0.0

price: float = 0.0

tvl: float = 0.0

volume: float = 0.0

class fractal.core.entities.uniswap_v3_lp.UniswapV3LPInternalState(token0_amount: float = 0.0, token1_amount: float = 0.0, price_init: float = 0.0, price_lower: float = 0.0, price_upper: float = 0.0, liquidity: float = 0.0, cash: float = 0.0)[source]

Bases: object

Represents the internal state of an UniswapV3 LP entity.

token0_amount

The amount of token0.

Type:: float

token1_amount

The amount of token1.

Type:: float

price_init

The position initial price.

Type:: float

price_lower

The range lower price.

Type:: float

price_upper

The range upper price.

Type:: float

liquidity

The position liquidity.

Type:: float

cash

The cash balance.

Type:: float

cash: float = 0.0

liquidity: float = 0.0

price_init: float = 0.0

price_lower: float = 0.0

price_upper: float = 0.0

token0_amount: float = 0.0

token1_amount: float = 0.0

fractal.core.entities.uniswap_v3_spot module

class fractal.core.entities.uniswap_v3_spot.UniswapV3SpotEntity(*args, trading_fee: float = 0.003, **kwargs)[source]

Bases: BaseSpotEntity

Represents an entity for trading on the Uniswap V3 Spot protocol.

action_buy(amount_in_notional: float)[source]

Executes a buy action on the Uniswap V3 Spot protocol.

Parameters:: amount_in_notional (float, optional) – The amount to buy in notional value.
Raises:: ValueError – If there is not enough cash to buy.

action_deposit(amount_in_notional: float)[source]

Executes a deposit action on the Uniswap V3 Spot protocol.

Parameters:: amount_in_notional (float) – The amount to deposit in notional value.

action_sell(amount_in_product: float)[source]

Executes a sell action on the Uniswap V3 Spot protocol.

Parameters:: amount_in_product (float, optional) – The amount to sell in product value.
Raises:: ValueError – If there is not enough product to sell.

action_withdraw(amount_in_notional: float)[source]

Executes a withdraw action on the Uniswap V3 Spot protocol.

Parameters:: amount_in_notional (float, optional) – The amount to withdraw in notional value.
Raises:: ValueError – If there is not enough cash to withdraw.

property balance: float

Calculates the balance of the Uniswap V3 Spot entity.

Returns:: The balance of the entity.
Return type:: float

update_state(state: UniswapV3SpotGlobalState, *args, **kwargs) → None[source]

Updates the global state of the Uniswap V3 Spot protocol.

Parameters:: state (UniswapV3SpotGlobalState) – The new global state.

exception fractal.core.entities.uniswap_v3_spot.UniswapV3SpotEntityException[source]: Bases: EntityException

class fractal.core.entities.uniswap_v3_spot.UniswapV3SpotGlobalState(price: float = 0.0)[source]

Bases: GlobalState

price: float = 0.0

class fractal.core.entities.uniswap_v3_spot.UniswapV3SpotInternalState(amount: float = 0.0, cash: float = 0.0)[source]

Bases: InternalState

amount: float = 0.0

cash: float = 0.0

Module contents

class fractal.core.entities.AaveEntity(*args, max_ltv: float = 0.8, liq_thr: float = 0.85, **kwargs)[source]

Bases: BaseLendingEntity

Represents an Aave isolated market entity.

action_borrow(amount_in_product: float)[source]

Borrows an amount on the Aave protocol.

Parameters:: amount_in_product (float, optional) – The amount to borrow in product value.

action_deposit(amount_in_notional: float) → None[source]

Deposits the specified amount in notional value into the entity. Each entity stores the cash balance in notional value.

Parameters:: amount_in_notional (float) – The amount to be deposited in notional value.

action_redeem(amount_in_product: float)[source]

Redeems an amount on the Aave protocol.

Parameters:: amount_in_product (float, optional) – The amount to redeem in product value.

action_withdraw(amount_in_notional: float) → None[source]

Withdraws the specified amount from the entity’s account. Each entity stores the cash balance in notional value.

Parameters:: amount_in_notional (float) – The amount to withdraw in notional value.

property balance: float

Calculates the balance of the Aave entity.

Aave entity balance is calculated as the difference between the collateral and the borrowed amount.

Returns:: The balance of the Aave entity.
Return type:: float

calculate_repay(target_ltv: float) → float[source]

Calculates the amount to repay in order to reach the target loan-to-value ratio.

Parameters:: target_ltv (float) – The target loan-to-value ratio.
Returns:: The amount to repay in product value.
Return type:: float

check_liquidation()[source]

Checks if the entity is eligible for liquidation.

Liquidation occurs when the LTV ratio exceeds the liquidation threshold.

property ltv: float

Calculates the loan-to-value (LTV) ratio of the Aave entity.

LTV ratio is calculated as the ratio of the borrowed amount to the collateral.

Returns:: The LTV ratio.
Return type:: float

update_state(state: AaveGlobalState)[source]

class fractal.core.entities.AaveGlobalState(notional_price: float = 0.0, product_price: float = 0.0, lending_rate: float = 0.0, borrowing_rate: float = 0.0)[source]

Bases: object

Represents the global state of the Aave protocol.

notional_price

The notional price.

Type:: float

product_price

The product price.

Type:: float

lending_rate

The lending rate.

Type:: float

borrowing_rate

The borrowing rate.

Type:: float

borrowing_rate: float = 0.0

lending_rate: float = 0.0

notional_price: float = 0.0

product_price: float = 0.0

class fractal.core.entities.BaseHedgeEntity[source]

Bases: BaseEntity

Base class for Hedge entities.

Hedge entities are entities that can open positions on the exchange.

abstract action_open_position(amount_in_product: float)[source]

Opens a position on the protocol.

Parameters:: amount_in_product (float, optional) – The amount to open in product value.

abstract property leverage: float

Returns the leverage of the entity.

Returns:: The leverage of the entity.
Return type:: float

abstract property size: float

Returns the size of the entity.

Returns:: The size of the entity.
Return type:: float

class fractal.core.entities.BaseLendingEntity[source]

Bases: BaseEntity

Base class for Lending entities.

Lending entities are entities that can lend and borrow on the protocol.

abstract action_borrow(amount_in_product: float)[source]

Borrows an amount on the protocol.

Parameters:: amount_in_product (float, optional) – The amount to borrow in product value.

abstract action_redeem(amount_in_product: float)[source]

Redeems an amount on the protocol.

Parameters:: amount_in_product (float, optional) – The amount to redeem in product value.

class fractal.core.entities.BasePoolEntity[source]

Bases: BaseEntity

Base class for Pool entity.

Pool entity is responsible for managing the position in the pool. It can open and close the position in the pool.

abstract action_close_position()[source]: Close position in pool.

abstract action_open_position(amount_in_notional: float, *args, **kwargs)[source]

Open position in pool.

Parameters:: amount_in_notional (float) – amount in notional

class fractal.core.entities.BaseSpotEntity[source]

Bases: BaseEntity

Base class for Spot entity.

Spot entity is responsible for managing the position in the spot market. We can buy and sell the product in the spot market.

abstract action_buy(amount_in_notional: float)[source]

Executes a buy action on the protocol.

Parameters:: amount_in_notional (float, optional) – The amount to buy in notional value.
Raises:: EntityException – If there is not enough cash to buy.

abstract action_sell(amount_in_product: float)[source]

Executes a sell action on the protocol.

Parameters:: amount_in_product (float, optional) – The amount to sell in product value.
Raises:: EntityException – If there is not enough product to sell.

class fractal.core.entities.GMXV2Entity(*args, trading_fee: float = 0.001, liquidation_leverage: float = 100, **kwargs)[source]

Bases: BaseHedgeEntity

Represents a GMX isolated market entity.

action_deposit(amount_in_notional: float)[source]

Deposits a specified amount of notional into the entity’s collateral.

Parameters:: amount_in_notional (float) – The amount of notional to deposit.

action_open_position(amount_in_product: float)[source]

Opens a position with a specified amount of product.

Parameters:: amount_in_product (float) – The amount of product to open the position with.

action_withdraw(amount_in_notional: float) → float[source]

Withdraws a specified amount of notional from the entity’s collateral.

Parameters:: amount_in_notional (float) – The amount of notional to withdraw.
Returns:: The remaining balance after the withdrawal.
Return type:: float
Raises:: ValueError – If there is not enough balance to withdraw.

property balance

Calculates the current balance of the entity.

Balance is a sum of the collateral and the PNL. :returns: The current balance. :rtype: float

property leverage

Calculates the leverage of the entity.

The leverage is the absolute ratio of the total position size to the balance. :returns: The leverage. :rtype: float

property pnl: float

Calculates the total profit and loss (PNL) of all positions.

PNL is a sum of PNLs of all positions. :returns: The total PNL. :rtype: float

property size

Calculates the total size of all positions.

Size is a sum of all position amounts. :returns: The total size. :rtype: float

update_state(state: GMXV2GlobalState, *args, **kwargs) → None[source]

Updates the entity’s state with the given global state.

Updates the global state.
Check liquidation.
Settle fundings and borrowings.

Parameters:: state (GMXGlobalState) – The global state to update with.

class fractal.core.entities.GMXV2GlobalState(price: float = 0.0, funding_rate_short: float = 0.0, funding_rate_long: float = 0.0, borrowing_rate_short: float = 0.0, borrowing_rate_long: float = 0.0, longs_pay_shorts: bool = True)[source]

Bases: GlobalState

Represents the global state of the GMX V2 entity.

GMX V2 has two-sided funding rates and borrowing rates.

price: float - The current price of the product. funding_rate_short: float - The short funding rate. funding_rate_long: float - The long funding rate. borrowing_rate_short: float - The short borrowing rate. borrowing_rate_long: float - The long borrowing rate. longs_pay_shorts: bool - Whether longs pay shorts.

borrowing_rate_long: float = 0.0

borrowing_rate_short: float = 0.0

funding_rate_long: float = 0.0

funding_rate_short: float = 0.0

longs_pay_shorts: bool = True

price: float = 0.0

class fractal.core.entities.GMXV2Position(amount: float, entry_price: float)[source]

Bases: object

A position in the GMXHedge. It includes the amount and the entry price of the position.

pnl(price: float) → float[source]

Calculates the profit and loss (PNL) of the position.

PNL = Amount * (Price - Entry Price)

class fractal.core.entities.StakedETHEntity(*args, trading_fee: float = 0.003, **kwargs)[source]

Bases: BaseSpotEntity

Represents an entity for trading on the StakedETH token. This is a simple entity that can buy, sell, deposit, and withdraw stETH. Also this entity control staking rate.

action_buy(amount_in_notional: float)[source]

Executes a buy action on the StakedETH protocol.

Parameters:: amount_in_notional (float, optional) – The amount to buy in notional value.
Raises:: ValueError – If there is not enough cash to buy.

action_deposit(amount_in_notional: float)[source]

Executes a deposit action on the StakedETH protocol.

Parameters:: amount_in_notional (float) – The amount to deposit in notional value.

action_sell(amount_in_product: float)[source]

Executes a sell action on the StakedETH protocol.

Parameters:: amount_in_product (float, optional) – The amount to sell in product value.
Raises:: ValueError – If there is not enough product to sell.

action_withdraw(amount_in_notional: float)[source]

Executes a withdraw action on the StakedETH protocol.

Parameters:: amount_in_notional (float, optional) – The amount to withdraw in notional value.
Raises:: ValueError – If there is not enough cash to withdraw.

property balance: float

Calculates the balance of the StakedETH entity.

The balance is calculated as the sum of the amount of stETH and the cash balance. :returns: The balance of the entity. :rtype: float

update_state(state: StakedETHGlobalState, *args, **kwargs) → None[source]

Updates the global state of the StakedETH protocol. 1. Updates the global state. 2. Add staking rewards to the internal state.

Parameters:: state (StakedETHGlobalState) – The new global state.

class fractal.core.entities.StakedETHGlobalState(price: float = 0.0, rate: float = 0.0)[source]

Bases: GlobalState

Represents the global state of any LST ETH token.

price

The price of the stETH.

Type:: float

rate

The rate of the .

Type:: float

price: float = 0.0

rate: float = 0.0

class fractal.core.entities.UniswapV2LPConfig(fees_rate: float = 0.005, token0_decimals: int = 18, token1_decimals: int = 18, trading_fee: float = 0.003)[source]

Bases: object

Represents the configuration of an UniswapV2 LP entity.

fees_rate

The fees rate.

Type:: float

token0_decimals

The token0 decimals.

Type:: int

token1_decimals

The token1 decimals.

Type:: int

trading_fee

The trading fee.

Type:: float

fees_rate: float = 0.005

token0_decimals: int = 18

token1_decimals: int = 18

trading_fee: float = 0.003

class fractal.core.entities.UniswapV2LPEntity(config: UniswapV2LPConfig, *args, **kwargs)[source]

Bases: BasePoolEntity

Represents an Uniswap V2-like LP entity.

It maintains exact 50-50 position of token0 and token1 in the pool.

action_close_position()[source]: Close the position in the LP entity.

action_deposit(amount_in_notional: float) → None[source]

Deposit funds into the LP entity.

Parameters:: amount_in_notional (float) – The amount to deposit.

action_open_position(amount_in_notional: float) → None[source]

Open a position in the LP entity.

Parameters:: amount_in_notional (float) – The amount to invest.

action_withdraw(amount_in_notional: float) → None[source]

Withdraw funds from the LP entity.

Parameters:: amount_in_notional (float) – The amount to withdraw.

property balance: float

Returns the balance of the LP entity.

Returns:: The balance of the LP entity.
Return type:: float

calculate_fees() → float[source]: Calculate fees for position :returns: acc fees for position :rtype: float

update_state(state: UniswapV2LPGlobalState) → None[source]

Update the state of the LP entity.

Update the global state.

2. Update token0 and token1 amounts following AMM formula. :param state: The state of the pool. :type state: UniswapV2LPGlobalState

class fractal.core.entities.UniswapV2LPGlobalState(tvl: float = 0.0, volume: float = 0.0, fees: float = 0.0, liquidity: float = 0.0, price: float = 0.0)[source]

Bases: object

Represents the global state of the UniswapV2 LP entity.

tvl

The total value locked.

Type:: float

volume

The trading volume.

Type:: float

fees

The trading fees.

Type:: float

liquidity

The pool liquidity.

Type:: float

price

The pool price [token1 / token0].

Type:: float

fees: float = 0.0

liquidity: float = 0.0

price: float = 0.0

tvl: float = 0.0

volume: float = 0.0

class fractal.core.entities.UniswapV3LPConfig(fees_rate: float = 0.005, token0_decimals: int = 18, token1_decimals: int = 18, trading_fee: float = 0.003)[source]

Bases: object

Represents the configuration of an UniswapV3 LP entity.

fees_rate

The fees rate.

Type:: float

token0_decimals

The token0 decimals.

Type:: int

token1_decimals

The token1 decimals.

Type:: int

trading_fee

The trading fee.

Type:: float

fees_rate: float = 0.005

token0_decimals: int = 18

token1_decimals: int = 18

trading_fee: float = 0.003

class fractal.core.entities.UniswapV3LPEntity(config: UniswapV3LPConfig, *args, **kwargs)[source]

Bases: BasePoolEntity

Represents an Uniswap V3 LP entity.

It maintains single position in the V3 pool.

action_close_position()[source]: Close the position in the LP entity.

action_deposit(amount_in_notional: float) → None[source]

Deposit funds into the LP entity.

Parameters:: amount_in_notional (float) – The amount to deposit.

action_open_position(amount_in_notional: float, price_lower: float, price_upper: float) → None[source]

Open a position in the LP entity.

Parameters:

amount_in_notional (float) – The amount to invest.
price_lower (float) – The lower price of the range.
price_upper (float) – The upper price of the range.

action_withdraw(amount_in_notional: float) → None[source]

Withdraw funds from the LP entity.

Parameters:: amount_in_notional (float) – The amount to withdraw.

property balance: float

Returns the balance of the LP entity.

Returns:: The balance of the LP entity.
Return type:: float

calculate_fees() → float[source]

Parameters:

position (UniswapV3Position) – position to which calc fees
pool_state (PoolState) – pool state

Returns:

acc fees for position

Return type:

float

calculate_position(deposit_amount: float, price_current: float, price_lower: float, price_upper: float) → str[source]

Add position to positions dict

Parameters:

deposit_amount (float) – deposited token amount in token1
price_current (float) – token1/token0 price
price_upper (float) – upper price bound
price_lower (float) – lower price bound

Returns:

id of position

Return type:

id (str)

calculate_position_from_notional(deposit_amount_in_notional: float, price_current: float, price_lower: float, price_upper: float) → str[source]

Add a new position by notional amount. !Notional amount is the amount of token1!

Parameters:

deposit_amount_in_notional (float) – deposited token amount in token1
price_current (float) – token1/token0 price
price_upper (float) – upper price bound
price_lower (float) – lower price bound

Returns:

id of position

Return type:

id (str)

get_desired_token0_amount(deposit_amount: float, price_current: float, price_lower: float, price_upper: float) → float[source]

Returns desired token0 amount for position

Parameters:

deposit_amount (float) – deposited token amount in token1
price_current (float) – token1/token0 price
price_upper (float) – upper price bound
price_lower (float) – lower price bound

Returns:

desired token0 amount for position

Return type:

desired_token0_amount (float)

price_to_tick(price: float) → float[source]

tick_to_price(tick: float) → float[source]

update_state(state: UniswapV3LPGlobalState) → None[source]

Update the state of the LP entity.

Update the global state.
Update token0 and token1 amounts following Uniswap V3 formula.
Calculate fees and add to cash balance.

Parameters:: state (UniswapV3LPGlobalState) – The state of the pool.

class fractal.core.entities.UniswapV3LPGlobalState(tvl: float = 0.0, volume: float = 0.0, fees: float = 0.0, liquidity: float = 0.0, price: float = 0.0)[source]

Bases: object

Represents the global state of the UniswapV3 LP entity.

tvl

The total value locked.

Type:: float

volume

The trading volume.

Type:: float

fees

The trading fees.

Type:: float

liquidity

The pool liquidity.

Type:: float

price

The pool price [token1 / token0].

Type:: float

fees: float = 0.0

liquidity: float = 0.0

price: float = 0.0

tvl: float = 0.0

volume: float = 0.0

class fractal.core.entities.UniswapV3SpotEntity(*args, trading_fee: float = 0.003, **kwargs)[source]

Bases: BaseSpotEntity

Represents an entity for trading on the Uniswap V3 Spot protocol.

action_buy(amount_in_notional: float)[source]

Executes a buy action on the Uniswap V3 Spot protocol.

Parameters:: amount_in_notional (float, optional) – The amount to buy in notional value.
Raises:: ValueError – If there is not enough cash to buy.

action_deposit(amount_in_notional: float)[source]

Executes a deposit action on the Uniswap V3 Spot protocol.

Parameters:: amount_in_notional (float) – The amount to deposit in notional value.

action_sell(amount_in_product: float)[source]

Executes a sell action on the Uniswap V3 Spot protocol.

Parameters:: amount_in_product (float, optional) – The amount to sell in product value.
Raises:: ValueError – If there is not enough product to sell.

action_withdraw(amount_in_notional: float)[source]

Executes a withdraw action on the Uniswap V3 Spot protocol.

Parameters:: amount_in_notional (float, optional) – The amount to withdraw in notional value.
Raises:: ValueError – If there is not enough cash to withdraw.

property balance: float

Calculates the balance of the Uniswap V3 Spot entity.

Returns:: The balance of the entity.
Return type:: float

update_state(state: UniswapV3SpotGlobalState, *args, **kwargs) → None[source]

Updates the global state of the Uniswap V3 Spot protocol.

Parameters:: state (UniswapV3SpotGlobalState) – The new global state.

class fractal.core.entities.UniswapV3SpotGlobalState(price: float = 0.0)[source]

Bases: GlobalState

price: float = 0.0