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:
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

__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:
Return type:

None