ostium-python-sdk 0.2.107__tar.gz → 2.0.0__tar.gz

{ostium_python_sdk-0.2.107 → ostium_python_sdk-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: ostium-python-sdk
-Version: 0.2.107
+Version: 2.0.0
 Summary: A python based SDK developed for interacting with Ostium, a leveraged trading application for trading currencies, commodities, indices, crypto and more.
 Home-page: https://github.com/0xOstium/ostium-python-sdk
 Author: ami@ostium.io
@@ -86,8 +86,38 @@ First, install the package with development dependencies:
 pip install -e ".[dev]"
 ```
 
-Then run the tests:
+## Running tests
+
+### Run specific tests
 
+```bash
+pytest -v tests/test_trade_liquidation_price.py
+pytest -v tests/test_funding.py
+pytest -v tests/test_trade_get_tp_price.py
+pytest -v tests/test_trade_get_sl_price.py
+pytest -v tests/test_current_trade_profit_p.py
+pytest -v tests/test_top_up_with_collateral.py
+pytest -v tests/test_top_up_with_leverage.py
+pytest -v tests/test_remove_collateral_with_collateral.py
+pytest -v tests/test_remove_collateral_from_leverage.py
+pytest -v tests/test_current_total_profit_p.py
+pytest -v tests/test_current_trade_profit_raw.py
+pytest -v tests/test_current_total_profit_raw.py
+pytest -v tests/test_get_trade_funding_fee.py
+pytest -v tests/test_get_trade_rollover_fee.py 
+
+
+
+
+
+
+
+
+
+
+```
+
+### Run ALL tests
 ```bash
 pytest
 ```
@@ -514,6 +544,11 @@ All notable changes to the Ostium Python SDK will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+
+## [2.0.0] - 2025-03-04
+
+Version 2.0
+
 ## [0.2.1] - 2025-02-21
 
 ### Added

{ostium_python_sdk-0.2.107 → ostium_python_sdk-2.0.0}/README.md

@@ -47,8 +47,38 @@ First, install the package with development dependencies:
 pip install -e ".[dev]"
 ```
 
-Then run the tests:
+## Running tests
 
+### Run specific tests
+
+```bash
+pytest -v tests/test_trade_liquidation_price.py
+pytest -v tests/test_funding.py
+pytest -v tests/test_trade_get_tp_price.py
+pytest -v tests/test_trade_get_sl_price.py
+pytest -v tests/test_current_trade_profit_p.py
+pytest -v tests/test_top_up_with_collateral.py
+pytest -v tests/test_top_up_with_leverage.py
+pytest -v tests/test_remove_collateral_with_collateral.py
+pytest -v tests/test_remove_collateral_from_leverage.py
+pytest -v tests/test_current_total_profit_p.py
+pytest -v tests/test_current_trade_profit_raw.py
+pytest -v tests/test_current_total_profit_raw.py
+pytest -v tests/test_get_trade_funding_fee.py
+pytest -v tests/test_get_trade_rollover_fee.py 
+
+
+
+
+
+
+
+
+
+
+```
+
+### Run ALL tests
 ```bash
 pytest
 ```

{ostium_python_sdk-0.2.107 → ostium_python_sdk-2.0.0}/ostium_python_sdk/constants.py

@@ -5,6 +5,7 @@ from decimal import Decimal
 
 MAX_PROFIT_P = Decimal('900')  # 900% * PRECISION_6
 MAX_STOP_LOSS_P = Decimal('85')
+MIN_LOSS_P = Decimal("-100")  # Adjust if you need a different minimum
 
 PRECISION_2 = Decimal('100')
 PRECISION_6 = Decimal('1000000')

ostium_python_sdk-2.0.0/ostium_python_sdk/formulae.py

@@ -0,0 +1,313 @@
+from decimal import Decimal, getcontext, ROUND_DOWN
+from .constants import MAX_PROFIT_P, MIN_LOSS_P, MAX_STOP_LOSS_P, PRECISION_16, PRECISION_2, PRECISION_6, PRECISION_12, PRECISION_18, LIQ_THRESHOLD_P
+from typing import Dict
+from .scscript.funding import getPendingAccFundingFees, getTargetFundingRate
+
+quantization_6 = Decimal('0.000001')
+quantization_18 = Decimal('0.000000000000000001')
+
+# v2 (formulae v1.3.3)
+
+
+def GetTakeProfitPrice(open_price: Decimal, profit_p: Decimal, leverage: Decimal, is_long: bool) -> Decimal:
+    open_price = Decimal(open_price)
+    profit_p = Decimal(profit_p)
+    leverage = Decimal(leverage)
+
+    price_diff = (open_price * profit_p) / (leverage * Decimal('100'))
+
+    if (is_long):
+        tp_price = open_price + price_diff
+    else:
+        tp_price = open_price - price_diff
+
+    return Decimal(tp_price if tp_price > 0 else '0')
+
+# v2 (formulae v1.3.3)
+
+
+def GetStopLossPrice(open_price: Decimal, loss_p: Decimal, leverage: Decimal, is_long: bool) -> Decimal:
+    open_price = Decimal(open_price)
+    loss_p = Decimal(loss_p)
+    leverage = Decimal(leverage)
+
+    # price_diff matches your existing TP logic style, except using 'loss_p'
+    price_diff = (open_price * loss_p) / (leverage * Decimal('100'))
+
+    sl_price = open_price - price_diff if is_long else open_price + price_diff
+    return sl_price if sl_price > 0 else Decimal('0')
+
+# v2 (formulae v1.3.3)
+
+
+def CurrentTradeProfitP(
+    open_price: Decimal,
+    current_price: Decimal,
+    long: bool,
+    leverage: Decimal,
+    highest_leverage: Decimal
+) -> Decimal:
+    leverage_to_use = leverage if leverage > highest_leverage else highest_leverage
+    if long:
+        price_diff = current_price - open_price
+    else:
+        price_diff = open_price - current_price
+
+    profit_p = (price_diff / open_price) * leverage_to_use * Decimal("100")
+
+    if profit_p >= MAX_PROFIT_P:
+        profit_p = MAX_PROFIT_P
+
+    profit_p *= (leverage / leverage_to_use)
+
+    return profit_p
+
+# v2 (formulae v1.3.3)
+
+
+def TopUpWithCollateral(
+    leverage: Decimal,
+    collateral: Decimal,
+    added_collateral: Decimal
+) -> Decimal:
+    new_leverage = (collateral * leverage) / (collateral + added_collateral)
+    return new_leverage
+
+# v2 (formulae v1.3.3)
+
+
+def TopUpWithLeverage(
+    leverage: Decimal,
+    desired_leverage: Decimal,
+    collateral: Decimal
+) -> Decimal:
+    added_c = (collateral * leverage) / desired_leverage - collateral
+    return added_c
+
+# v2 (formulae v1.3.3)
+
+
+def RemoveCollateralWithCollateral(
+    leverage: Decimal,
+    collateral: Decimal,
+    removed_collateral: Decimal
+) -> Decimal:
+    new_leverage = (collateral * leverage) / (collateral - removed_collateral)
+    return new_leverage
+
+# v2 (formulae v1.3.3)
+
+
+def RemoveCollateralFromLeverage(
+    leverage: Decimal,
+    desired_leverage: Decimal,
+    collateral: Decimal
+) -> Decimal:
+    added_c = collateral - (collateral * leverage / desired_leverage)
+    return added_c
+
+# tbd - used by SDK
+# v2 (formulae v1.3.3)
+
+
+def GetTradeLiquidationPrice(
+    open_price: Decimal,
+    long: bool,
+    collateral: Decimal,
+    leverage: Decimal,
+    rollover_fee: Decimal,
+    funding_fee: Decimal
+) -> Decimal:
+    print(
+        f"***** GetTradeLiquidationPrice: open_price: {open_price}, long: {long}, collateral: {collateral}, leverage: {leverage}, rollover_fee: {rollover_fee}, funding_fee: {funding_fee}")
+
+    liq_price_distance = (
+        open_price *
+        (collateral * (LIQ_THRESHOLD_P) / Decimal(100) - rollover_fee - funding_fee) /
+        collateral /
+        leverage
+    )
+
+    liq_price = open_price - liq_price_distance if long else open_price + liq_price_distance
+    liq_price = liq_price if liq_price > 0 else 0
+    return liq_price
+
+
+# ???
+def GetCurrentRolloverFee(
+    acc_rollover: str,
+    last_rollover_block: str,
+    rollover_fee_per_block: str,
+    latest_block: str
+) -> Decimal:
+    try:
+        acc_rollover = Decimal(acc_rollover)
+        last_rollover_block = Decimal(last_rollover_block)
+        rollover_fee_per_block = Decimal(rollover_fee_per_block)
+        latest_block = Decimal(latest_block)
+        current_fee = acc_rollover + \
+            (latest_block - last_rollover_block) * rollover_fee_per_block
+        return current_fee
+
+    except Exception as error:
+        raise Exception(f"Unable to compute Current Rollover Fee: {error}")
+
+
+# v2 (formulae v1.3.3)
+def GetTradeRolloverFee(
+    trade_rollover: Decimal,
+    current_rollover: Decimal,
+    collateral: Decimal,
+    leverage: Decimal
+) -> Decimal:
+    rollover_fee = (current_rollover - trade_rollover) * collateral * leverage
+    return rollover_fee
+
+
+# Gets the funding fee (abs) for an open trade (up to this block, aka based on current_funding up till this block)
+# v2 (formulae v1.3.3)
+def GetTradeFundingFee(
+    trade_funding: Decimal,
+    current_funding: Decimal,
+    collateral: Decimal,
+    leverage: Decimal
+) -> Decimal:
+    print(
+        f"======> GetTradeFundingFee: trade_funding: {trade_funding}, current_funding: {current_funding}, collateral: {collateral}, leverage: {leverage}")
+    funding_fee = (current_funding - trade_funding) * collateral * leverage
+    return funding_fee
+
+
+def GetPriceImpact(
+    mid_price: str,
+    bid_price: str,
+    ask_price: str,
+    is_open: bool,
+    is_long: bool,
+) -> dict:
+    try:
+        mid_price = Decimal(mid_price)
+        bid_price = Decimal(bid_price)
+        ask_price = Decimal(ask_price)
+
+        if (mid_price == 0):
+            return {
+                'priceImpactP': str(0),
+                'priceAfterImpact': str(0)
+            }
+
+        above_spot = is_open == is_long
+        used_price = ask_price if above_spot else bid_price
+        priceImpactP = 100 * (abs(mid_price - used_price) / mid_price)
+
+        return {
+            'priceImpactP': str(priceImpactP),
+            'priceAfterImpact': str(used_price)
+        }
+
+    except Exception as error:
+        raise Exception(f"Unable to compute Price Impact: {error}")
+
+
+# calculates the gross (without fees) profit (abs) of an open trade
+
+# calculates the net profit (after fees) of an open trade (abs)
+# v2 (formulae v1.3.3)
+def CurrentTradeProfitRaw(
+    open_price: Decimal,
+    current_price: Decimal,
+    long: bool,
+    leverage: Decimal,
+    highest_leverage: Decimal,
+    collateral: Decimal
+) -> Decimal:
+    profit_p = CurrentTradeProfitP(
+        open_price,
+        current_price,
+        long,
+        leverage,
+        highest_leverage
+    )
+    profit = (collateral * profit_p) / Decimal("100")
+    return profit
+
+# v2 (formulae v1.3.3)
+
+
+def CurrentTotalProfitRaw(
+    open_price: Decimal,
+    current_price: Decimal,
+    long: bool,
+    leverage: Decimal,
+    highest_leverage: Decimal,
+    collateral: Decimal,
+    rollover_fee: Decimal,
+    funding_fee: Decimal
+) -> Decimal:
+    # Get trade profit
+    trade_profit = CurrentTradeProfitRaw(
+        open_price,
+        current_price,
+        long,
+        leverage,
+        highest_leverage,
+        collateral
+    )
+
+    # Subtract fees
+    total_profit = trade_profit - \
+        rollover_fee - funding_fee
+
+    return total_profit
+
+
+# v2 (formulae v1.3.3)
+def CurrentTotalProfitP(total_profit: Decimal, collateral: Decimal) -> Decimal:
+    profit_p = (total_profit * Decimal("100")) / collateral
+    if profit_p <= MIN_LOSS_P:
+        profit_p = MIN_LOSS_P
+    return profit_p
+
+
+def GetFundingRate(
+    accPerOiLong: str,
+    accPerOiShort: str,
+    lastFundingRate: str,
+    maxFundingFeePerBlock: str,
+    lastUpdateBlock: str,
+    latestBlock: str,
+    oiLong: str,
+    oiShort: str,
+    oiCap: str,
+    hillInflectionPoint: str,
+    hillPosScale: str,
+    hillNegScale: str,
+    springFactor: str,
+    sFactorUpScaleP: str,
+    sFactorDownScaleP: str,
+    verbose: bool = False
+):
+    acc_funding_long, acc_funding_short, latest_funding_rate, target_fr = getPendingAccFundingFees(
+        blockNumber=Decimal(latestBlock),
+        lastUpdateBlock=Decimal(lastUpdateBlock),
+        valueLong=Decimal(accPerOiLong) / PRECISION_18,
+        valueShort=Decimal(accPerOiShort) / PRECISION_18,
+        openInterestUsdcLong=Decimal(oiLong) / PRECISION_6,
+        openInterestUsdcShort=Decimal(oiShort) / PRECISION_6,
+        OiCap=Decimal(oiCap) / PRECISION_6,
+        maxFundingFeePerBlock=Decimal(maxFundingFeePerBlock) / PRECISION_18,
+        lastFundingRate=Decimal(lastFundingRate) / PRECISION_18,
+        hillInflectionPoint=Decimal(hillInflectionPoint) / PRECISION_18,
+        hillPosScale=Decimal(hillPosScale) / PRECISION_2,
+        hillNegScale=Decimal(hillNegScale) / PRECISION_2,
+        springFactor=Decimal(springFactor) / PRECISION_18,
+        sFactorUpScale=Decimal(sFactorUpScaleP) / PRECISION_2,
+        sFactorDownScaleP=Decimal(sFactorDownScaleP) / PRECISION_2
+    )
+
+    return {
+        'accFundingLong': acc_funding_long,
+        'accFundingShort': acc_funding_short,
+        'latestFundingRate': latest_funding_rate,
+        'targetFundingRate': target_fr
+    }

ostium_python_sdk-2.0.0/ostium_python_sdk/formulae_wrapper.py

@@ -0,0 +1,204 @@
+from decimal import Decimal
+from .formulae import (PRECISION_18, PRECISION_2, PRECISION_6, GetCurrentRolloverFee, GetFundingRate,
+                       GetTradeFundingFee, GetTradeLiquidationPrice, GetTradeRolloverFee,
+                       GetPriceImpact, CurrentTradeProfitRaw,
+                       CurrentTotalProfitRaw, CurrentTotalProfitP)
+
+
+# TBD - used by SDK
+# returns the funding_fee_long_per_block, funding_fee_short_per_block
+
+
+def get_funding_fee_long_short(pair_info, block_number, verbose=False):
+    funding_rate_raw = GetFundingRate(
+        pair_info['accFundingLong'],
+        pair_info['accFundingShort'],
+        pair_info['lastFundingRate'],
+        pair_info['maxFundingFeePerBlock'],
+        pair_info['lastFundingBlock'],
+        str(block_number),
+        pair_info['longOI'],
+        pair_info['shortOI'],
+        pair_info['maxOI'],
+        pair_info['hillInflectionPoint'],
+        pair_info['hillPosScale'],
+        pair_info['hillNegScale'],
+        pair_info['springFactor'],
+        pair_info['sFactorUpScaleP'],
+        pair_info['sFactorDownScaleP'],
+        verbose
+    )
+
+    # Convert latest funding rate to decimal
+    latest_rate = Decimal(
+        funding_rate_raw['latestFundingRate']) / PRECISION_18  # Fixed key name
+
+    # Convert OI values to decimal
+    long_oi = Decimal(pair_info['longOI']) / PRECISION_18
+    short_oi = Decimal(pair_info['shortOI']) / PRECISION_18
+
+    if funding_rate_raw['longsPay']:
+        # If longs pay, they get negative rate
+        long_rate = -latest_rate
+        # Shorts receive proportional to OI ratio
+        short_rate = latest_rate * long_oi / \
+            short_oi if short_oi > 0 else Decimal('0')
+    else:
+        # If shorts pay, they get negative rate
+        short_rate = -latest_rate
+        # Longs receive proportional to OI ratio
+        long_rate = latest_rate * short_oi / \
+            long_oi if long_oi > 0 else Decimal('0')
+
+    return float(long_rate), float(short_rate)
+
+# TBD - used by SDK
+# Gets an open trade metrics: such as the open pnl, rollover, funding, liquidation price, price impact, etc.
+
+
+def get_trade_metrics(trade_details, price_data, block_number, verbose=False):
+    """
+    Calculate PNL and related metrics for a trade.
+    """
+    if not trade_details or not price_data or not block_number:
+        return {
+            'pnl': 0,
+            'pnl_percent': 0,
+            'rollover': 0,
+            'funding': 0,
+            'total_profit': 0,
+            'net_pnl': 0,
+            'net_value': 0,
+            'liquidation_price': 0
+        }
+
+    pair_info = trade_details['pair']
+    # Calculate current rollover fee
+    current_rollover_raw = GetCurrentRolloverFee(
+        pair_info['accRollover'],
+        pair_info['lastRolloverBlock'],
+        pair_info['rolloverFeePerBlock'],
+        str(block_number)
+    )
+
+    if verbose:
+        print(f"Current rollover fee: {current_rollover_raw}")
+
+    trade_rollover_fee = GetTradeRolloverFee(
+        Decimal(trade_details['rollover']) / PRECISION_18,
+        Decimal(current_rollover_raw) / PRECISION_18,
+        Decimal(trade_details['collateral']) / PRECISION_6,
+        Decimal(trade_details['leverage']) / PRECISION_2
+    )
+
+    if verbose:
+        print(f"Trade Rollover fee: {trade_rollover_fee}")
+        if (trade_rollover_fee != 0):
+            print(f"***** Trade Rollover fee is not 0: {trade_rollover_fee}")
+    # Get funding rate
+    funding_rate_raw = GetFundingRate(
+        pair_info['accFundingLong'],
+        pair_info['accFundingShort'],
+        pair_info['lastFundingRate'],
+        pair_info['maxFundingFeePerBlock'],
+        pair_info['lastFundingBlock'],
+        str(block_number),
+        pair_info['longOI'],
+        pair_info['shortOI'],
+        pair_info['maxOI'],
+        pair_info['hillInflectionPoint'],
+        pair_info['hillPosScale'],
+        pair_info['hillNegScale'],
+        pair_info['springFactor'],
+        pair_info['sFactorUpScaleP'],
+        pair_info['sFactorDownScaleP'],
+        verbose
+    )
+
+    if verbose:
+        print(f"Funding rate: {funding_rate_raw}")
+
+    # Calculate funding fee
+    trade_funding_fee = GetTradeFundingFee(
+        Decimal(trade_details['funding']) / PRECISION_18,
+        Decimal(funding_rate_raw['accFundingLong']) if trade_details['isBuy'] else Decimal(
+            funding_rate_raw['accFundingShort']),
+        Decimal(trade_details['collateral']) / PRECISION_6,
+        Decimal(trade_details['leverage']) / PRECISION_2
+    )
+
+    if verbose:
+        print(f"trade_funding_fee: {trade_funding_fee}")
+
+    # Calculate liquidation price
+    trade_liquidation_price = GetTradeLiquidationPrice(
+        Decimal(trade_details['openPrice']) / PRECISION_18,
+        trade_details['isBuy'],
+        Decimal(trade_details['collateral']) / PRECISION_6,
+        Decimal(trade_details['leverage']) / PRECISION_2,
+        Decimal(trade_rollover_fee),
+        Decimal(trade_funding_fee)
+    )
+
+    if verbose:
+        print(f"trade_liquidation_price: {trade_liquidation_price}")
+
+    # Calculate price impact
+    is_open = False  # Get the price assuming a close
+
+    price_impact_raw = GetPriceImpact(
+        str(int(Decimal(str(price_data['mid'])) * PRECISION_18)),
+        str(int(Decimal(str(price_data['bid'])) * PRECISION_18)),
+        str(int(Decimal(str(price_data['ask'])) * PRECISION_18)),
+        is_open,
+        trade_details['isBuy']
+    )
+    price_after_impact = price_impact_raw['priceAfterImpact']
+
+    # Calculate PNL (abs)
+    pnl_raw = CurrentTradeProfitRaw(
+        Decimal(trade_details['openPrice']) / PRECISION_18,
+        Decimal(price_after_impact) / PRECISION_18,
+        Decimal(trade_details['isBuy']),
+        Decimal(trade_details['leverage']) / PRECISION_2,
+        Decimal(trade_details['highestLeverage']) / PRECISION_2,
+        Decimal(trade_details['collateral']) / PRECISION_6
+    )
+
+    # Calculate total profit (abs)
+    total_profit_raw = CurrentTotalProfitRaw(
+        Decimal(trade_details['openPrice']) / PRECISION_18,
+        Decimal(price_after_impact) / PRECISION_18,
+        Decimal(trade_details['isBuy']),
+        Decimal(trade_details['leverage']) / PRECISION_2,
+        Decimal(trade_details['highestLeverage']) / PRECISION_2,
+        Decimal(trade_details['collateral']) / PRECISION_6,
+        Decimal(trade_rollover_fee),
+        Decimal(trade_funding_fee)
+    )
+
+    # Calculate PNL percentage
+    pnl_percent_raw = CurrentTotalProfitP(
+        Decimal(total_profit_raw), Decimal(trade_details['collateral']) / PRECISION_6)
+
+    # Convert values to proper decimals
+    pnl = Decimal(pnl_raw)
+    pnl_percent = Decimal(pnl_percent_raw)
+    net_pnl = Decimal(total_profit_raw)
+    total_profit = Decimal(total_profit_raw)
+    funding = Decimal(trade_funding_fee)
+    rollover = Decimal(trade_rollover_fee)
+    net_value = net_pnl + (Decimal(trade_details['collateral']) / PRECISION_6)
+    price_impact = Decimal(price_after_impact) / PRECISION_18
+
+    return {
+        'pnl': float(pnl),
+        'pnl_percent': float(pnl_percent),
+        'rollover': float(rollover),
+        'funding': float(funding),
+        'total_profit': float(total_profit),  # same as net_pnl
+        'net_pnl': float(net_pnl),  # same as total_profit
+        'net_value': float(net_value),
+        'liquidation_price': float(trade_liquidation_price),
+        'price_impact': float(price_impact)
+    }

{ostium_python_sdk-0.2.107 → ostium_python_sdk-2.0.0}/ostium_python_sdk/scscript/funding.py

@@ -30,7 +30,9 @@ def getTargetFundingRate(normalizedOiDelta, hillInflectionPoint, maxFundingFeePe
     
     return (maxFundingFeePerBlock * targetFr).quantize(quantization_18, rounding=ROUND_DOWN)
 
-
+#
+# returns the accFundingLong, accFundingShort, latestFundingRate (per block), targetFr (per block)
+#
 def getPendingAccFundingFees(
         blockNumber: Decimal,
         lastUpdateBlock: Decimal,
@@ -48,7 +50,7 @@ def getPendingAccFundingFees(
         sFactorUpScale: Decimal,
         sFactorDownScaleP: Decimal,
     ):
-
+    # print(f"********* getPendingAccFundingFees *********")
     numBlocks = blockNumber - lastUpdateBlock
     openInterestMax = max(openInterestUsdcLong, openInterestUsdcShort)
     normalizedOiDelta = ((openInterestUsdcLong - openInterestUsdcShort).quantize(quantization_6, rounding=ROUND_DOWN) / max(OiCap, openInterestMax).quantize(quantization_6, rounding=ROUND_DOWN)).quantize(quantization_6, rounding=ROUND_DOWN)