v14.3.2 (#49)

Author: truemagic-coder

.coverage

@@ -887,7 +887,10 @@ config = {
 - `limit_order` - Calculate making_amount and taking_amount for limit orders
   - Params: `usd_amount`, `input_price_usd`, `input_decimals`, `output_price_usd`, `output_decimals`, `price_change_percentage`
   - 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)
+  - `price_change_percentage`: How much MORE output you want than current market. ALWAYS POSITIVE for limit orders:
+    - "0.5" = get 0.5% more output (buy the dip - wait for output token to drop)
+    - "5" = get 5% more output (sell high - wait for input token to rise)
+    - "0" = current market price (fills immediately)
 
 - `limit_order_info` - Calculate trigger price and USD values for displaying order info
   - Params: `making_amount`, `taking_amount`, `input_price_usd`, `output_price_usd`, `input_decimals`, `output_decimals`
@@ -920,13 +923,13 @@ User: "limit buy BONK when price drops 0.5% with $10 of SOL"
    - input_decimals=9
    - output_price_usd="0.00001" (BONK)
    - output_decimals=5
-   - price_change_percentage="-0.5"
+   - price_change_percentage="0.5"  # Want 0.5% MORE BONK than current market
    
    Returns:
    - making_amount="71428571" (SOL in lamports)
-   - taking_amount="100502512562" (BONK in smallest units)
+   - taking_amount="100500000000" (BONK - 0.5% more than current would give)
 
-3. privy_trigger with those exact amounts
+3. privy_trigger with those exact amounts - order waits until you can get 0.5% more BONK
 ```
 
 ## 🧩 Plugin Development

README.md

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

pyproject.toml

@@ -179,14 +179,23 @@ def calculate_limit_order_amounts(
     """
     Calculate both making_amount and taking_amount for a limit order.
 
+    The price_change_percentage indicates how much MORE output you want than current market:
+    - Positive = you want MORE output tokens (order waits for better price)
+      Example: 0.5 = get 0.5% more output tokens (buy the dip)
+      Example: 5 = get 5% more output tokens (sell high)
+    - Zero = current market price (will fill immediately if liquidity available)
+    - Negative = accept LESS output (will fill immediately, rare use case)
+
+    For "buy the dip 0.5%" → use 0.5 (you want 0.5% more tokens)
+    For "sell high 5%" → use 5 (you want 5% more of the output token)
+
     Args:
         input_usd_amount: USD value of input token to spend
         input_price_usd: Current price of input token in USD
         input_decimals: Decimals of input token
         output_price_usd: Current price of output token in USD
         output_decimals: Decimals of output token
-        price_change_percentage: Target price change for output token
-                                 (e.g., "-0.5" for 0.5% lower = buy the dip)
+        price_change_percentage: How much MORE output you want (positive = wait for better price)
 
     Returns:
         Dict with making_amount, taking_amount (both in smallest units)
@@ -195,15 +204,23 @@ def calculate_limit_order_amounts(
     input_human = usd_to_token_amount(input_usd_amount, input_price_usd)
     making_amount = human_to_smallest_units(input_human, input_decimals)
 
-    # Calculate target output price with percentage change
-    target_output_price = apply_percentage_change(
-        output_price_usd, price_change_percentage
+    # Apply percentage change to get the adjusted USD value
+    # Positive percentage = you want MORE output (input worth more, or output cheaper)
+    # We ADD the percentage to the input USD value to get more output tokens
+    pct = Decimal(str(price_change_percentage))
+    adjusted_usd = Decimal(str(input_usd_amount)) * (
+        Decimal("1") + pct / Decimal("100")
     )
 
-    # Calculate output token amount at target price
-    output_human = usd_to_token_amount(input_usd_amount, target_output_price)
+    # Calculate output token amount at current price for the adjusted USD value
+    output_human = usd_to_token_amount(str(adjusted_usd), output_price_usd)
     taking_amount = human_to_smallest_units(output_human, output_decimals)
 
+    # Calculate what the target output price would be (for display purposes)
+    # trigger_price = input_usd / output_tokens
+    # If we're asking for more output, the effective output price we're paying is lower
+    target_output_price = str(Decimal(str(input_usd_amount)) / Decimal(output_human))
+
     return {
         "making_amount": making_amount,
         "taking_amount": taking_amount,
@@ -377,7 +394,14 @@ def get_schema(self) -> Dict[str, Any]:
                 },
                 "price_change_percentage": {
                     "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.",
+                    "description": (
+                        "How much MORE output you want compared to current market (for 'limit_order'). "
+                        "ALWAYS POSITIVE for limit orders that wait for better prices: "
+                        "e.g., '0.5' = get 0.5%% more output (buy the dip), "
+                        "'5' = get 5%% more output (sell high). "
+                        "Pass '0' for current market price (will fill immediately). "
+                        "Negative values mean accepting LESS than market (rare, fills immediately)."
+                    ),
                 },
                 "making_amount": {
                     "type": "string",

sakit/token_math.py

@@ -244,40 +244,43 @@ def test_limit_order_at_current_price(self):
         assert result["taking_amount"] == "100000000000"
 
     def test_limit_order_buy_the_dip(self):
-        """Should calculate limit order for buying at lower price."""
+        """Should calculate limit order for buying the dip (get more output by waiting)."""
         result = calculate_limit_order_amounts(
             input_usd_amount="10",
             input_price_usd="140",  # SOL
             input_decimals=9,
             output_price_usd="0.00001",  # BONK
             output_decimals=5,
-            price_change_percentage="-0.5",  # Buy when 0.5% lower
+            price_change_percentage="0.5",  # Want 0.5% MORE output (buy the dip)
         )
         # making_amount unchanged
         assert result["making_amount"] == "71428571"
-        # taking_amount: at 0.995 price, get MORE tokens
-        # $10 / $0.00000995 * 10^5 = 100,502,512,562 (rounded down)
+        # taking_amount: with +0.5%, we're asking for MORE output (1.005x)
+        # $10 * 1.005 / $0.00001 * 10^5 = 100,500,000,000
         taking = int(result["taking_amount"])
         assert taking > 100000000000  # More than at current price
         assert taking < 101000000000  # But not too much more
 
     def test_limit_order_sell_high(self):
-        """Should calculate limit order for selling at higher price."""
+        """Should calculate limit order for selling at higher price (get more output)."""
         result = calculate_limit_order_amounts(
             input_usd_amount="10",
             input_price_usd="0.00001",  # BONK
             input_decimals=5,
             output_price_usd="140",  # SOL
             output_decimals=9,
-            price_change_percentage="10",  # Sell when SOL is 10% higher
+            price_change_percentage="5",  # Want 5% MORE output (sell high)
         )
-        # At 10% higher SOL price ($154), get LESS SOL for same USD
+        # making: $10 / $0.00001 * 10^5 = 100,000,000,000
         making = int(result["making_amount"])
-        # $10 / $0.00001 * 10^5 = 100,000,000,000
         assert making == 100000000000
-        # taking: $10 / $154 * 10^9 = 64,935,064 (less SOL)
+        # taking: $10 * 1.05 / $140 * 10^9 = 75,000,000 (5% more SOL than current)
         taking = int(result["taking_amount"])
-        assert taking < 71428571  # Less than at current price
+        # Current would be $10 / $140 * 10^9 = 71,428,571
+        assert (
+            taking > 71428571
+        )  # More than at current price (we're asking for premium)
+        assert taking < 80000000  # Reasonable upper bound
 
 
 class TestCalculateLimitOrderInfo:
@@ -1084,7 +1087,7 @@ async def test_scenario_swap_2_dollars_of_sol(self, math_tool):
     async def test_scenario_limit_buy_bonk_with_10_dollars_sol(self, math_tool):
         """
         Scenario: "limit buy BONK when price drops 0.5% with $10 of SOL"
-        From the agent config example.
+        User wants 0.5% MORE BONK than current market (buy the dip).
         """
         # From Birdeye: SOL price=$140, decimals=9, BONK price=$0.00001, decimals=5
         result = await math_tool.execute(
@@ -1098,7 +1101,7 @@ async def test_scenario_limit_buy_bonk_with_10_dollars_sol(self, math_tool):
             input_decimals=9,
             output_price_usd="0.00001",  # BONK
             output_decimals=5,
-            price_change_percentage="-0.5",  # 0.5% lower
+            price_change_percentage="0.5",  # Want 0.5% MORE output (buy the dip)
         )
         assert result["status"] == "success"
 
@@ -1108,12 +1111,13 @@ async def test_scenario_limit_buy_bonk_with_10_dollars_sol(self, math_tool):
         assert making == 71428571
 
         # Verify taking_amount (BONK to receive)
-        # Target price = $0.00001 * 0.995 = $0.00000995
-        # $10 / $0.00000995 = 1,005,025.125... BONK
-        # In smallest units: 1,005,025.125 * 100,000 = 100,502,512,562
+        # With +0.5%, we want 0.5% more BONK
+        # Current: $10 / $0.00001 = 1,000,000 BONK
+        # With +0.5%: 1,000,000 * 1.005 = 1,005,000 BONK
+        # In smallest units: 1,005,000 * 100,000 = 100,500,000,000
         taking = int(result["taking_amount"])
         # Should be around 100.5 billion (12 digits)
-        assert len(str(taking)) == 12  # Verify digit count matches agent example
+        assert len(str(taking)) == 12  # Verify digit count
         assert taking > 100000000000  # More than at current price
 
     @pytest.mark.asyncio