LeverageEstimate#

API documentation for tradeexecutor.utils.leverage_calculations.LeverageEstimate Python class in Trading Strategy framework.

class LeverageEstimate[source]#

Bases: object

Estimate token quantities and fees for a leverage position.

A helper class to make sense out of fees when doing leveraged trading on 1delta / Aave.

When increasing short, the fees are allocated to the collateral we need to borrow

Opening short

Doing 3x ETH short
- Start with 10 USDC
- Deposit in Aave
- ETH price is 1,500 USD/ETH
- Using swap exact out method
- The short should be 20 USD worth of ETH, 29.99 USD collateral
Deposit 10 USDC to Aave
Open position with 1delta protocol contract
- 1delta takes inputs
- 1delta initiates swap for 0.0133333333333 WETH to 20 USDC (minus fees)
- Uniswap v3 calls back 1delta
- 1delta mints out USDC aToken from USDC we received from the swap
- We have now total 10 (originak deposit) + 19.99 USDC (new loan) in Aave
- 1delta borrows WETH for 0.0133333333333 WETH
- Uniswap is happy has we have WETH we did not have at the start of the process
Fee calculations
- Token in: Borrowed ETH (no fees) 13.3333333333
- Token out: 19.99 USDC (0.01 USD paid in fees)
Final outcome
- vWETH 0.0133333333
- aUSDC 29.99
Example transaction

** Close short **

Closing 3x short as described above
Closing position with 1delta
- Assume price is
- Get exact wWETH debt amount: 0.0112236255452078143 vWETH
- Start a swap process on Uniswap with WETH -> USDC for this amount
  
  There is no WETH yet in this point
  
  Uniswap will tell us how much USDC we will need later down the chain
- Uniswap calls 1delta fallback called with incoming WETH from the swap
  
  Aave loan is repaid with WETH
  
  Uniswap tells os the USDC needed to cover the swap cost
  
  Atoken USDC colleteral is converted back to USDC to cover the cost of the swap
  
  The amount of USDC here is fee inclusive to match 0.0112236255452078143 vWETH, so it is wWETH price + fees
- Total swap cost is = (0.0112236255452078143 / 0.9995) * ETH price
- Fees are 0.0005 * (0.0112236255452078143 / 0.9995) * ETH price = ETH amount * (fee / (1-fee))
Example transaction

__init__(starting_reserve, leverage, borrowed_quantity, borrowed_value, additional_collateral_quantity, total_collateral_quantity, total_borrowed_quantity, borrowed_asset_price, fee_tier, lp_fees, liquidation_price=None)#

Parameters:

starting_reserve (Decimal) –
leverage (float) –
borrowed_quantity (Decimal) –
borrowed_value (float) –
additional_collateral_quantity (Decimal) –
total_collateral_quantity (Decimal) –
total_borrowed_quantity (Decimal) –
borrowed_asset_price (float) –
fee_tier (float) –
lp_fees (float) –
liquidation_price (float | None) –

Return type:

None

Methods

`__init__`(starting_reserve, leverage, ...[, ...])
`close_short`(start_collateral, ...[, fee])	Reduce or close short position.
`open_short`(starting_reserve, leverage, ...)	Get borrow and colleteral size for a loan in leverage protocol trading.

Attributes

`liquidation_price`	What is the liquidation price for this position.
`starting_reserve`	Amount of USDC reserve we use for this position.
`leverage`	What was the leverage multiplier we used.
`borrowed_quantity`	Amount of the borrowed token we short.
`borrowed_value`	What is the borrowed asset value in USD
`additional_collateral_quantity`	This is the output when we buy/sell borrowed asset.
`total_collateral_quantity`	Amount of total collateral we have
`total_borrowed_quantity`	What is the total borrow amount after this ooperation
`borrowed_asset_price`
`fee_tier`	What was our swap fee tier
`lp_fees`	How much fees we are going to be.

starting_reserve: Decimal#

Amount of USDC reserve we use for this position.

Set to 0 when closing/reducing short position as the position is covered from the collateral.

leverage: float#

What was the leverage multiplier we used.

Short open: This is the leverage the user desired.

Short close/reduce: This is the leverage remaining.

borrowed_quantity: Decimal#

Amount of the borrowed token we short.

Positive if we increase our borrow.

Negative if we reduce or borrow.

borrowed_value: float#: What is the borrowed asset value in USD

additional_collateral_quantity: Decimal#

This is the output when we buy/sell borrowed asset.

Positive: We are selling WETH and adding this USDC to our debt.

Negative: We are buying WETH and need to convert this much of collateral to USDC to match the cost.

total_collateral_quantity: Decimal#

Amount of total collateral we have

Short open: This is starting reserve + additional collateral borrowed.

Short close: This is remaining collateral after converting it to cover the trade to close the short.

total_borrowed_quantity: Decimal#: What is the total borrow amount after this ooperation

borrowed_asset_price: float#

fee_tier: float#

What was our swap fee tier

E.g 0.0005 for 5 BPS.

lp_fees: float#

How much fees we are going to be.

Estimate swap fees.

liquidation_price: float | None = None#: What is the liquidation price for this position. If the price goes below this, the loan is liquidated.

static open_short(starting_reserve, leverage, borrowed_asset_price, shorting_pair, fee=0)[source]#

Get borrow and colleteral size for a loan in leverage protocol trading.

See calculate_sizes_for_leverage().

Note

Short only. Stablecoin collateral only.

Example:

from tradeexecutor.strategy.lending_protocol_leverage import LeverageEstimate

# Start with 10 USD
starting_capital = 10.0
leverage = 3.0
eth_price = 1634.4869

# This will borrow additional
# - 20 USDC as collateral
# - 0.01228645 WETH
estimate = LeverageEstimate.open_short(
    starting_capital,
    leverage,
    eth_price,
    fee=0.0005,
)

print("Estimated amounts for the short:", estimate)

Example output:

Estimated amounts for the short: <Leverage estimate
    leverage: 3.0
    reserve allocated (USDC): 10
    borrowed (vToken): 0.01223625591615325807353339610
    total collateral (aToken): 29.98999999999999999979183318
    LP fees: 0.01 USD
>

Parameters:

starting_capital – How much USDC we are going to deposit
leverage (float) – How much leverage we take
token_price – What is the price of a token we short
shorting_pair (TradingPairIdentifier) –
The synthetic trading pair for the lending pool short.

With aToken and vToken.
fee (float) –
What is the trading fee for swapping the borrowed asset to collateral.

TODO: Use the fee from the trading pair.
starting_reserve (float | decimal.Decimal) –
borrowed_asset_price (float) –

Returns:

borrow quantity, collateral quantity for the constructed loan

Return type:

LeverageEstimate

static close_short(start_collateral, start_borrowed, close_size, borrowed_asset_price, fee=0)[source]#

Reduce or close short position.

Calculate the trade mounts needed to close a short position.

Buy back shorted tokens
Release any collateral

See LeverageEstimate for fee calculation example.

Example:

estimate = LeverageEstimate.close_short(
    start_collateral=short_position.loan.collateral.quantity,
    start_borrowed=short_position.loan.borrowed.quantity,
    close_size=short_position.loan.borrowed.quantity,
    fee=weth_short_identifier_5bps.fee,
    borrowed_asset_price=1500.0,
)

assert estimate.leverage == 1.0  # Reduced USDC leverage to 1.0
assert estimate.additional_collateral_quantity == pytest.approx(Decimal(-20010.00500250125062552103147))  # USDC needed to reduce from collateral to close position + fees
assert estimate.borrowed_quantity == pytest.approx(Decimal(-13.33333333333333333333333333))  # How much ETH is bought to close the short
assert estimate.total_collateral_quantity == pytest.approx(Decimal(9979.99499749874937427080171))  # Collateral left after closing the position
assert estimate.total_borrowed_quantity == 0  # open vWETH debt left after close
assert estimate.lp_fees == pytest.approx(10.005002501250626)

We assume collateral is 1:1 USD.

Parameters:

start_collateral (Decimal) – How much collateral we have at start.
close_size (Decimal) –
How much debt to reduce.

Expressed in the amount of borrowed token quantity.
start_borrowed (Decimal) –
borrowed_asset_price (float) –
fee (float | None) –

Return type:

LeverageEstimate

Parameters:

starting_reserve (Decimal) –
leverage (float) –
borrowed_quantity (Decimal) –
borrowed_value (float) –
additional_collateral_quantity (Decimal) –
total_collateral_quantity (Decimal) –
total_borrowed_quantity (Decimal) –
borrowed_asset_price (float) –
fee_tier (float) –
lp_fees (float) –
liquidation_price (float | None) –

Return type:

None