v14.3.0 (#47)

Author: truemagic-coder

.coverage

@@ -889,6 +889,11 @@ config = {
   - Returns: `making_amount`, `taking_amount` (use these for privy_trigger)
   - `price_change_percentage`: Use "-0.5" for 0.5% lower (buy the dip), "10" for 10% higher (sell high)
 
+- `limit_order_info` - Calculate trigger price and USD values for displaying order info
+  - Params: `making_amount`, `taking_amount`, `input_price_usd`, `output_price_usd`
+  - Returns: `making_usd`, `taking_usd_at_current`, `trigger_price_usd`, `current_output_price_usd`, `price_difference_percent`, `should_fill_now`
+  - Use this when listing orders to show meaningful price info to users
+
 - `to_smallest_units` - Convert human amount to smallest units
   - Params: `human_amount`, `decimals`
   - Returns: `smallest_units`

README.md

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "sakit"
-version = "14.2.2"
+version = "14.3.0"
 description = "Solana Agent Kit"
 authors = ["Bevan Hunt <bevan@bevanhunt.com>"]
 license = "MIT"

pyproject.toml

@@ -213,6 +213,68 @@ def calculate_limit_order_amounts(
     }
 
 
+def calculate_limit_order_info(
+    making_amount: str,
+    taking_amount: str,
+    input_price_usd: str,
+    output_price_usd: str,
+) -> Dict[str, str]:
+    """
+    Calculate display info for a limit order from its amounts.
+
+    Use this when listing orders to show USD values and trigger prices.
+
+    Args:
+        making_amount: Human-readable amount of input token being sold
+        taking_amount: Human-readable amount of output token to receive
+        input_price_usd: Current market price of input token in USD
+        output_price_usd: Current market price of output token in USD
+
+    Returns:
+        Dict with USD values and trigger price info
+    """
+    try:
+        making = Decimal(str(making_amount))
+        taking = Decimal(str(taking_amount))
+        input_price = Decimal(str(input_price_usd))
+        output_price = Decimal(str(output_price_usd))
+
+        # Calculate USD values at current prices
+        making_usd = making * input_price
+        taking_usd_at_current = taking * output_price
+
+        # Calculate the trigger price (price per output token the order expects)
+        # trigger_price = making_usd / taking_amount
+        if taking > 0:
+            trigger_price = making_usd / taking
+        else:
+            trigger_price = Decimal("0")
+
+        # Calculate price difference from current market
+        if output_price > 0:
+            price_diff_pct = ((trigger_price - output_price) / output_price) * 100
+        else:
+            price_diff_pct = Decimal("0")
+
+        # Determine if order should fill (for buy orders, trigger >= current means fill)
+        # For a buy order: you want to buy when price drops TO trigger_price
+        # Order fills when current_price <= trigger_price
+        will_fill = output_price <= trigger_price
+
+        return {
+            "making_amount": str(making),
+            "taking_amount": str(taking),
+            "making_usd": str(making_usd),
+            "taking_usd_at_current": str(taking_usd_at_current),
+            "trigger_price_usd": str(trigger_price),
+            "current_output_price_usd": str(output_price),
+            "price_difference_percent": str(price_diff_pct),
+            "should_fill_now": will_fill,
+        }
+    except (InvalidOperation, ValueError) as e:
+        raise ValueError(f"Invalid limit order info calculation: {e}")
+
+
 class TokenMathTool(AutoTool):
     """
     Reliable token math calculations for swaps, transfers, and limit orders.
@@ -229,6 +291,7 @@ def __init__(self, registry: Optional[ToolRegistry] = None):
                 "Actions: 'swap' (for privy_ultra - returns smallest_units), "
                 "'transfer' (for privy_transfer - returns human-readable amount), "
                 "'limit_order' (for privy_trigger - returns making_amount and taking_amount), "
+                "'limit_order_info' (for displaying order list - calculates trigger price and USD values), "
                 "'to_smallest_units', 'to_human', 'usd_to_tokens'. "
                 "ALWAYS use this tool for any calculation - never do math yourself!"
             ),
@@ -245,6 +308,7 @@ def get_schema(self) -> Dict[str, Any]:
                         "swap",
                         "transfer",
                         "limit_order",
+                        "limit_order_info",
                         "to_smallest_units",
                         "to_human",
                         "usd_to_tokens",
@@ -254,6 +318,7 @@ def get_schema(self) -> Dict[str, Any]:
                         "'swap' - For privy_ultra: calculate smallest_units from USD amount, "
                         "'transfer' - For privy_transfer: calculate human-readable token amount from USD, "
                         "'limit_order' - For privy_trigger: calculate making_amount and taking_amount, "
+                        "'limit_order_info' - For displaying orders: calculate trigger price and USD values from order amounts, "
                         "'to_smallest_units' - Convert human amount to smallest units, "
                         "'to_human' - Convert smallest units to human readable, "
                         "'usd_to_tokens' - Calculate token amount from USD value"
@@ -289,7 +354,7 @@ def get_schema(self) -> Dict[str, Any]:
                 },
                 "output_price_usd": {
                     "type": "string",
-                    "description": "Output token price in USD (for 'limit_order'). Get from Birdeye. Pass empty string if not needed.",
+                    "description": "Output token price in USD (for 'limit_order', 'limit_order_info'). Get from Birdeye. Pass empty string if not needed.",
                 },
                 "output_decimals": {
                     "type": "integer",
@@ -299,6 +364,14 @@ def get_schema(self) -> Dict[str, Any]:
                     "type": "string",
                     "description": "Price change percentage for limit order (for 'limit_order'). E.g., '-0.5' for 0.5% lower (buy dip), '10' for 10% higher (sell high). Pass '0' for current price.",
                 },
+                "making_amount": {
+                    "type": "string",
+                    "description": "Human-readable amount of input token being sold (for 'limit_order_info'). From order's makingAmount field. Pass empty string if not needed.",
+                },
+                "taking_amount": {
+                    "type": "string",
+                    "description": "Human-readable amount of output token to receive (for 'limit_order_info'). From order's takingAmount field. Pass empty string if not needed.",
+                },
             },
             "required": [
                 "action",
@@ -312,6 +385,8 @@ def get_schema(self) -> Dict[str, Any]:
                 "output_price_usd",
                 "output_decimals",
                 "price_change_percentage",
+                "making_amount",
+                "taking_amount",
             ],
             "additionalProperties": False,
         }
@@ -333,6 +408,8 @@ async def execute(
         output_price_usd: str = "",
         output_decimals: int = 0,
         price_change_percentage: str = "0",
+        making_amount: str = "",
+        taking_amount: str = "",
     ) -> Dict[str, Any]:
         """Execute the math calculation."""
         action = action.lower().strip()
@@ -449,10 +526,41 @@ async def execute(
                     "message": f"${usd_amount} at price ${token_price_usd} = {result} tokens",
                 }
 
+            elif action == "limit_order_info":
+                # Calculate display info for a limit order from its amounts
+                if not all(
+                    [making_amount, taking_amount, input_price_usd, output_price_usd]
+                ):
+                    return {
+                        "status": "error",
+                        "message": "Missing required params for 'limit_order_info': making_amount, taking_amount, input_price_usd, output_price_usd",
+                    }
+                result = calculate_limit_order_info(
+                    making_amount=making_amount,
+                    taking_amount=taking_amount,
+                    input_price_usd=input_price_usd,
+                    output_price_usd=output_price_usd,
+                )
+                return {
+                    "status": "success",
+                    "action": "limit_order_info",
+                    "making_amount": result["making_amount"],
+                    "taking_amount": result["taking_amount"],
+                    "making_usd": result["making_usd"],
+                    "taking_usd_at_current": result["taking_usd_at_current"],
+                    "trigger_price_usd": result["trigger_price_usd"],
+                    "current_output_price_usd": result["current_output_price_usd"],
+                    "price_difference_percent": result["price_difference_percent"],
+                    "should_fill_now": result["should_fill_now"],
+                    "message": f"Order: sell {result['making_amount']} (${result['making_usd']}) for {result['taking_amount']} tokens. "
+                    f"Trigger price: ${result['trigger_price_usd']}, Current price: ${result['current_output_price_usd']} "
+                    f"({result['price_difference_percent']}% diff). Will fill now: {result['should_fill_now']}",
+                }
+
             else:
                 return {
                     "status": "error",
-                    "message": f"Unknown action: {action}. Valid: swap, limit_order, to_smallest_units, to_human, usd_to_tokens",
+                    "message": f"Unknown action: {action}. Valid: swap, transfer, limit_order, limit_order_info, to_smallest_units, to_human, usd_to_tokens",
                 }
 
         except ValueError as e:

sakit/token_math.py

@@ -19,6 +19,7 @@
     apply_percentage_change,
     calculate_swap_amount,
     calculate_limit_order_amounts,
+    calculate_limit_order_info,
 )
 
 
@@ -279,6 +280,104 @@ def test_limit_order_sell_high(self):
         assert taking < 71428571  # Less than at current price
 
 
+class TestCalculateLimitOrderInfo:
+    """Test calculate_limit_order_info function."""
+
+    def test_order_at_current_price(self):
+        """Should calculate info for order at current market price."""
+        # Order: sell 0.036 SOL for 521714 BONK
+        result = calculate_limit_order_info(
+            making_amount="0.036001982",
+            taking_amount="521714.66282",
+            input_price_usd="139",  # Current SOL price
+            output_price_usd="0.0000096",  # Current BONK price
+        )
+        # making_usd = 0.036 * 139 = ~$5
+        assert float(result["making_usd"]) == pytest.approx(5.00, rel=0.01)
+        # trigger_price = making_usd / taking_amount = $5 / 521714 = ~$0.00000958
+        trigger_price = float(result["trigger_price_usd"])
+        assert trigger_price == pytest.approx(0.00000958, rel=0.01)
+        # Current price is $0.0000096, trigger is ~$0.00000958
+        # Order wants to buy at LOWER price, so should NOT fill now
+        assert result["should_fill_now"] is False
+
+    def test_order_should_fill(self):
+        """Should detect when order should fill (price dropped to trigger)."""
+        result = calculate_limit_order_info(
+            making_amount="0.036",
+            taking_amount="521714",
+            input_price_usd="139",  # SOL price
+            output_price_usd="0.0000090",  # BONK price dropped below trigger
+        )
+        # trigger_price = $5 / 521714 = ~$0.00000958
+        # Current price = $0.0000090 which is BELOW trigger
+        # Order should fill now!
+        assert result["should_fill_now"] is True
+
+    def test_price_difference_calculation(self):
+        """Should calculate price difference correctly."""
+        result = calculate_limit_order_info(
+            making_amount="0.07",  # ~$10 at $140/SOL
+            taking_amount="1000000",  # 1M BONK
+            input_price_usd="140",
+            output_price_usd="0.00001",  # Current BONK price
+        )
+        # trigger_price = (0.07 * 140) / 1000000 = $0.0000098 per BONK
+        trigger_price = float(result["trigger_price_usd"])
+        assert trigger_price == pytest.approx(0.0000098, rel=0.01)
+        # price_diff = (trigger - current) / current * 100
+        # = (0.0000098 - 0.00001) / 0.00001 * 100 = -2%
+        price_diff = float(result["price_difference_percent"])
+        assert price_diff == pytest.approx(-2.0, rel=0.1)
+
+    def test_usd_values(self):
+        """Should calculate USD values correctly."""
+        result = calculate_limit_order_info(
+            making_amount="1",  # 1 SOL
+            taking_amount="10000",  # 10,000 USDC
+            input_price_usd="140",
+            output_price_usd="1",  # USDC
+        )
+        # making_usd = 1 * 140 = $140
+        assert result["making_usd"] == "140"
+        # taking_usd_at_current = 10000 * 1 = $10,000
+        assert result["taking_usd_at_current"] == "10000"
+        # trigger_price = $140 / 10000 = $0.014 per USDC
+        assert float(result["trigger_price_usd"]) == pytest.approx(0.014, rel=0.001)
+
+    def test_zero_taking_amount(self):
+        """Should handle zero taking amount (edge case)."""
+        result = calculate_limit_order_info(
+            making_amount="1",
+            taking_amount="0",  # Zero output
+            input_price_usd="140",
+            output_price_usd="1",
+        )
+        # trigger_price should be 0 when taking is 0
+        assert result["trigger_price_usd"] == "0"
+
+    def test_zero_output_price(self):
+        """Should handle zero output price (edge case)."""
+        result = calculate_limit_order_info(
+            making_amount="1",
+            taking_amount="1000",
+            input_price_usd="140",
+            output_price_usd="0",  # Zero price
+        )
+        # price_diff should be 0 when output_price is 0
+        assert result["price_difference_percent"] == "0"
+
+    def test_invalid_amounts(self):
+        """Should raise error for invalid amounts."""
+        with pytest.raises(ValueError):
+            calculate_limit_order_info(
+                making_amount="invalid",
+                taking_amount="100",
+                input_price_usd="140",
+                output_price_usd="1",
+            )
+
+
 # =============================================================================
 # Integration Tests for Tool
 # =============================================================================
@@ -486,6 +585,77 @@ async def test_limit_order_missing_params(self, math_tool):
         assert result["status"] == "error"
 
 
+class TestTokenMathToolExecuteLimitOrderInfo:
+    """Test 'limit_order_info' action."""
+
+    @pytest.mark.asyncio
+    async def test_limit_order_info_success(self, math_tool):
+        """Should calculate order info correctly."""
+        result = await math_tool.execute(
+            action="limit_order_info",
+            usd_amount="",
+            token_price_usd="",
+            decimals=0,
+            human_amount="",
+            smallest_units="",
+            input_price_usd="139",  # SOL current price
+            input_decimals=0,
+            output_price_usd="0.0000096",  # BONK current price
+            output_decimals=0,
+            price_change_percentage="0",
+            making_amount="0.036",  # Selling 0.036 SOL
+            taking_amount="521714",  # Buying 521k BONK
+        )
+        assert result["status"] == "success"
+        assert result["action"] == "limit_order_info"
+        # Check USD values
+        assert float(result["making_usd"]) == pytest.approx(5.0, rel=0.01)
+        # Check trigger price
+        assert "trigger_price_usd" in result
+        assert "should_fill_now" in result
+
+    @pytest.mark.asyncio
+    async def test_limit_order_info_should_fill(self, math_tool):
+        """Should detect when order should fill."""
+        result = await math_tool.execute(
+            action="limit_order_info",
+            usd_amount="",
+            token_price_usd="",
+            decimals=0,
+            human_amount="",
+            smallest_units="",
+            input_price_usd="139",
+            input_decimals=0,
+            output_price_usd="0.0000090",  # Price dropped below trigger
+            output_decimals=0,
+            price_change_percentage="0",
+            making_amount="0.036",
+            taking_amount="521714",
+        )
+        assert result["status"] == "success"
+        assert result["should_fill_now"] is True
+
+    @pytest.mark.asyncio
+    async def test_limit_order_info_missing_params(self, math_tool):
+        """Should return error when params missing."""
+        result = await math_tool.execute(
+            action="limit_order_info",
+            usd_amount="",
+            token_price_usd="",
+            decimals=0,
+            human_amount="",
+            smallest_units="",
+            input_price_usd="",  # Missing
+            input_decimals=0,
+            output_price_usd="",  # Missing
+            output_decimals=0,
+            price_change_percentage="0",
+            making_amount="",  # Missing
+            taking_amount="",  # Missing
+        )
+        assert result["status"] == "error"
+
+
 class TestTokenMathToolExecuteToSmallestUnits:
     """Test 'to_smallest_units' action."""