shll-skills 5.5.1 → 5.5.2

package/SKILL.md

@@ -153,6 +153,8 @@ If `-l/--listing-id` is omitted, `setup-guide` auto-selects an active listing fr
 - `shll-run four-buy --token <address> -a <bnb> -k <tokenId>`
 - `shll-run four-sell --token <address> -a <tokenAmount> -k <tokenId>`
 
+`four-buy` amount unit is BNB, not USD. If user gives a USD target, convert to BNB first and confirm final BNB amount before execution.
+
 ### Read-only and audit
 
 - `shll-run portfolio -k <tokenId>`

package/dist/index.js

@@ -2747,13 +2747,17 @@ fourBuyCmd.action(async (opts) => {
     const tokenAddr = opts.token;
     const slippage = Number(opts.slippage);
     const bnbAmount = parseAmount(opts.amount, 18);
+    if (bnbAmount <= 0n) {
+      outputError("Invalid amount.", "four-buy amount must be a positive BNB value.");
+      process.exit(1);
+    }
     const info = await publicClient.readContract({
       address: FOUR_MEME_HELPER_V3,
       abi: FOUR_MEME_HELPER_ABI,
       functionName: "getTokenInfo",
       args: [tokenAddr]
     });
-    const [version, tokenManager, quote, , , , , , , , , liquidityAdded] = info;
+    const [version, tokenManager, quote, , , minTradingFee, , , , , , liquidityAdded] = info;
     if (liquidityAdded) {
       output({ status: "error", message: "Token has already migrated to DEX. Use the 'swap' command instead of 'four-buy'." });
       process.exit(1);
@@ -2763,6 +2767,20 @@ fourBuyCmd.action(async (opts) => {
       output({ status: "error", message: `Token uses BEP20 quote (${quote}), not BNB. BEP20 quote pairs are not yet supported in this tool.` });
       process.exit(1);
     }
+    if (bnbAmount < minTradingFee) {
+      outputError(
+        "Input amount is below Four.meme minimum trading fee threshold.",
+        "Increase --amount and retry.",
+        {
+          token: tokenAddr,
+          inputBnb: opts.amount,
+          inputWei: bnbAmount.toString(),
+          minTradingFeeWei: minTradingFee.toString(),
+          minTradingFeeBnb: (Number(minTradingFee) / 1e18).toFixed(6)
+        }
+      );
+      process.exit(1);
+    }
     const tryBuyResult = await publicClient.readContract({
       address: FOUR_MEME_HELPER_V3,
       abi: FOUR_MEME_HELPER_ABI,
@@ -2770,6 +2788,48 @@ fourBuyCmd.action(async (opts) => {
       args: [tokenAddr, 0n, bnbAmount]
     });
     const [, , estimatedAmount, estimatedCost, estimatedFee, amountMsgValue] = tryBuyResult;
+    if (amountMsgValue < minTradingFee) {
+      outputError(
+        "Computed payable amount is below Four.meme minimum trading fee threshold.",
+        "Increase --amount and retry.",
+        {
+          token: tokenAddr,
+          inputBnb: opts.amount,
+          payableWei: amountMsgValue.toString(),
+          minTradingFeeWei: minTradingFee.toString(),
+          minTradingFeeBnb: (Number(minTradingFee) / 1e18).toFixed(6)
+        }
+      );
+      process.exit(1);
+    }
+    if (estimatedAmount <= 0n || amountMsgValue <= 0n) {
+      outputError(
+        "four-buy quote returned zero output.",
+        "Requested amount is likely too small for this market. Increase --amount and retry.",
+        {
+          token: tokenAddr,
+          inputBnb: opts.amount,
+          estimatedCostWei: estimatedCost.toString(),
+          estimatedFeeWei: estimatedFee.toString()
+        }
+      );
+      process.exit(1);
+    }
+    const vaultBnbBalance = await publicClient.getBalance({ address: vault });
+    if (amountMsgValue > vaultBnbBalance) {
+      outputError(
+        "Vault BNB balance is insufficient for four-buy.",
+        "Deposit more BNB to vault or reduce --amount, then retry.",
+        {
+          vault,
+          requiredBnb: (Number(amountMsgValue) / 1e18).toFixed(6),
+          availableBnb: (Number(vaultBnbBalance) / 1e18).toFixed(6),
+          requiredWei: amountMsgValue.toString(),
+          availableWei: vaultBnbBalance.toString()
+        }
+      );
+      process.exit(1);
+    }
     const minAmount = estimatedAmount * BigInt(100 - slippage) / 100n;
     const alignedMinAmount = minAmount / 1000000000n * 1000000000n;
     output({
@@ -2800,7 +2860,19 @@ fourBuyCmd.action(async (opts) => {
       output({ status: "rejected", reason: simResult.reason });
       process.exit(0);
     }
-    const result = await client.execute(tokenId, action, true);
+    let result;
+    try {
+      result = await client.execute(tokenId, action, true);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown execution revert";
+      outputError(
+        "four-buy execution reverted on-chain.",
+        "Likely market-side failure (amount too small, temporary pool state change, or token-side constraint).",
+        { reason: message, token: tokenAddr, inputBnb: opts.amount }
+      );
+      process.exit(1);
+      return;
+    }
     output({
       status: "success",
       hash: result.hash,

package/dist/index.mjs

@@ -2259,13 +2259,17 @@ fourBuyCmd.action(async (opts) => {
     const tokenAddr = opts.token;
     const slippage = Number(opts.slippage);
     const bnbAmount = parseAmount(opts.amount, 18);
+    if (bnbAmount <= 0n) {
+      outputError("Invalid amount.", "four-buy amount must be a positive BNB value.");
+      process.exit(1);
+    }
     const info = await publicClient.readContract({
       address: FOUR_MEME_HELPER_V3,
       abi: FOUR_MEME_HELPER_ABI,
       functionName: "getTokenInfo",
       args: [tokenAddr]
     });
-    const [version, tokenManager, quote, , , , , , , , , liquidityAdded] = info;
+    const [version, tokenManager, quote, , , minTradingFee, , , , , , liquidityAdded] = info;
     if (liquidityAdded) {
       output({ status: "error", message: "Token has already migrated to DEX. Use the 'swap' command instead of 'four-buy'." });
       process.exit(1);
@@ -2275,6 +2279,20 @@ fourBuyCmd.action(async (opts) => {
       output({ status: "error", message: `Token uses BEP20 quote (${quote}), not BNB. BEP20 quote pairs are not yet supported in this tool.` });
       process.exit(1);
     }
+    if (bnbAmount < minTradingFee) {
+      outputError(
+        "Input amount is below Four.meme minimum trading fee threshold.",
+        "Increase --amount and retry.",
+        {
+          token: tokenAddr,
+          inputBnb: opts.amount,
+          inputWei: bnbAmount.toString(),
+          minTradingFeeWei: minTradingFee.toString(),
+          minTradingFeeBnb: (Number(minTradingFee) / 1e18).toFixed(6)
+        }
+      );
+      process.exit(1);
+    }
     const tryBuyResult = await publicClient.readContract({
       address: FOUR_MEME_HELPER_V3,
       abi: FOUR_MEME_HELPER_ABI,
@@ -2282,6 +2300,48 @@ fourBuyCmd.action(async (opts) => {
       args: [tokenAddr, 0n, bnbAmount]
     });
     const [, , estimatedAmount, estimatedCost, estimatedFee, amountMsgValue] = tryBuyResult;
+    if (amountMsgValue < minTradingFee) {
+      outputError(
+        "Computed payable amount is below Four.meme minimum trading fee threshold.",
+        "Increase --amount and retry.",
+        {
+          token: tokenAddr,
+          inputBnb: opts.amount,
+          payableWei: amountMsgValue.toString(),
+          minTradingFeeWei: minTradingFee.toString(),
+          minTradingFeeBnb: (Number(minTradingFee) / 1e18).toFixed(6)
+        }
+      );
+      process.exit(1);
+    }
+    if (estimatedAmount <= 0n || amountMsgValue <= 0n) {
+      outputError(
+        "four-buy quote returned zero output.",
+        "Requested amount is likely too small for this market. Increase --amount and retry.",
+        {
+          token: tokenAddr,
+          inputBnb: opts.amount,
+          estimatedCostWei: estimatedCost.toString(),
+          estimatedFeeWei: estimatedFee.toString()
+        }
+      );
+      process.exit(1);
+    }
+    const vaultBnbBalance = await publicClient.getBalance({ address: vault });
+    if (amountMsgValue > vaultBnbBalance) {
+      outputError(
+        "Vault BNB balance is insufficient for four-buy.",
+        "Deposit more BNB to vault or reduce --amount, then retry.",
+        {
+          vault,
+          requiredBnb: (Number(amountMsgValue) / 1e18).toFixed(6),
+          availableBnb: (Number(vaultBnbBalance) / 1e18).toFixed(6),
+          requiredWei: amountMsgValue.toString(),
+          availableWei: vaultBnbBalance.toString()
+        }
+      );
+      process.exit(1);
+    }
     const minAmount = estimatedAmount * BigInt(100 - slippage) / 100n;
     const alignedMinAmount = minAmount / 1000000000n * 1000000000n;
     output({
@@ -2312,7 +2372,19 @@ fourBuyCmd.action(async (opts) => {
       output({ status: "rejected", reason: simResult.reason });
       process.exit(0);
     }
-    const result = await client.execute(tokenId, action, true);
+    let result;
+    try {
+      result = await client.execute(tokenId, action, true);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown execution revert";
+      outputError(
+        "four-buy execution reverted on-chain.",
+        "Likely market-side failure (amount too small, temporary pool state change, or token-side constraint).",
+        { reason: message, token: tokenAddr, inputBnb: opts.amount }
+      );
+      process.exit(1);
+      return;
+    }
     output({
       status: "success",
       hash: result.hash,

package/dist/mcp.js

@@ -2035,19 +2035,47 @@ server.tool(
     if (expiryCheck.blocked) return { content: expiryCheck.content };
     const tokenAddr = token;
     const bnbAmount = parseAmount(amount, 18);
+    if (bnbAmount <= 0n) {
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            status: "error",
+            message: "Invalid amount. four_buy amount must be a positive BNB value."
+          })
+        }]
+      };
+    }
+    const vault = await policyClient.getVault(tokenId);
     const info = await publicClient.readContract({
       address: FOUR_MEME_HELPER_V3,
       abi: FOUR_MEME_HELPER_ABI,
       functionName: "getTokenInfo",
       args: [tokenAddr]
     });
-    const [version, tokenManager, quote, , , , , , , , , liquidityAdded] = info;
+    const [version, tokenManager, quote, , , minTradingFee, , , , , , liquidityAdded] = info;
     if (liquidityAdded) {
       return { content: [{ type: "text", text: JSON.stringify({ status: "error", message: "Token has already migrated to DEX. Use the 'swap' tool instead." }) }] };
     }
     if (quote !== "0x0000000000000000000000000000000000000000") {
       return { content: [{ type: "text", text: JSON.stringify({ status: "error", message: `Token uses BEP20 quote (${quote}), not BNB. BEP20 pairs not yet supported.` }) }] };
     }
+    if (bnbAmount < minTradingFee) {
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            status: "error",
+            message: "Input amount is below Four.meme minimum trading fee threshold.",
+            next_step: "Increase amount and retry.",
+            token: tokenAddr,
+            inputWei: bnbAmount.toString(),
+            minTradingFeeWei: minTradingFee.toString(),
+            minTradingFeeBnb: (Number(minTradingFee) / 1e18).toFixed(6)
+          })
+        }]
+      };
+    }
     const tryBuyResult = await publicClient.readContract({
       address: FOUR_MEME_HELPER_V3,
       abi: FOUR_MEME_HELPER_ABI,
@@ -2055,6 +2083,53 @@ server.tool(
       args: [tokenAddr, 0n, bnbAmount]
     });
     const [, , estimatedAmount, , estimatedFee, amountMsgValue] = tryBuyResult;
+    if (amountMsgValue < minTradingFee) {
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            status: "error",
+            message: "Computed payable amount is below Four.meme minimum trading fee threshold.",
+            next_step: "Increase amount and retry.",
+            token: tokenAddr,
+            payableWei: amountMsgValue.toString(),
+            minTradingFeeWei: minTradingFee.toString(),
+            minTradingFeeBnb: (Number(minTradingFee) / 1e18).toFixed(6)
+          })
+        }]
+      };
+    }
+    if (estimatedAmount <= 0n || amountMsgValue <= 0n) {
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            status: "error",
+            message: "four_buy quote returned zero output. Requested amount is likely too small for this market.",
+            next_step: "Increase amount and retry.",
+            token: tokenAddr
+          })
+        }]
+      };
+    }
+    const vaultBnbBalance = await publicClient.getBalance({ address: vault });
+    if (amountMsgValue > vaultBnbBalance) {
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            status: "error",
+            message: "Vault BNB balance is insufficient for four_buy.",
+            next_step: "Deposit more BNB to vault or reduce amount, then retry.",
+            vault,
+            requiredBnb: (Number(amountMsgValue) / 1e18).toFixed(6),
+            availableBnb: (Number(vaultBnbBalance) / 1e18).toFixed(6),
+            requiredWei: amountMsgValue.toString(),
+            availableWei: vaultBnbBalance.toString()
+          })
+        }]
+      };
+    }
     const minAmount = estimatedAmount * BigInt(100 - slippage) / 100n;
     const alignedMinAmount = minAmount / 1000000000n * 1000000000n;
     let data;
@@ -2066,7 +2141,23 @@ server.tool(
     const action = { target: tokenManager, value: amountMsgValue, data };
     const sim = await policyClient.validate(tokenId, action);
     if (!sim.ok) return { content: [{ type: "text", text: JSON.stringify({ status: "rejected", reason: sim.reason, ...policyRejectionHelp(sim.reason, token_id) }) }] };
-    const result = await policyClient.execute(tokenId, action, true);
+    let result;
+    try {
+      result = await policyClient.execute(tokenId, action, true);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown execution revert";
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            status: "error",
+            message: "four_buy execution reverted on-chain",
+            reason: message,
+            hint: "This is usually market-side failure (amount too small, temporary pool state change, or token-side constraint), not a PolicyGuard rejection."
+          })
+        }]
+      };
+    }
     return {
       content: [{
         type: "text",

package/dist/mcp.mjs

@@ -1547,19 +1547,47 @@ server.tool(
     if (expiryCheck.blocked) return { content: expiryCheck.content };
     const tokenAddr = token;
     const bnbAmount = parseAmount(amount, 18);
+    if (bnbAmount <= 0n) {
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            status: "error",
+            message: "Invalid amount. four_buy amount must be a positive BNB value."
+          })
+        }]
+      };
+    }
+    const vault = await policyClient.getVault(tokenId);
     const info = await publicClient.readContract({
       address: FOUR_MEME_HELPER_V3,
       abi: FOUR_MEME_HELPER_ABI,
       functionName: "getTokenInfo",
       args: [tokenAddr]
     });
-    const [version, tokenManager, quote, , , , , , , , , liquidityAdded] = info;
+    const [version, tokenManager, quote, , , minTradingFee, , , , , , liquidityAdded] = info;
     if (liquidityAdded) {
       return { content: [{ type: "text", text: JSON.stringify({ status: "error", message: "Token has already migrated to DEX. Use the 'swap' tool instead." }) }] };
     }
     if (quote !== "0x0000000000000000000000000000000000000000") {
       return { content: [{ type: "text", text: JSON.stringify({ status: "error", message: `Token uses BEP20 quote (${quote}), not BNB. BEP20 pairs not yet supported.` }) }] };
     }
+    if (bnbAmount < minTradingFee) {
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            status: "error",
+            message: "Input amount is below Four.meme minimum trading fee threshold.",
+            next_step: "Increase amount and retry.",
+            token: tokenAddr,
+            inputWei: bnbAmount.toString(),
+            minTradingFeeWei: minTradingFee.toString(),
+            minTradingFeeBnb: (Number(minTradingFee) / 1e18).toFixed(6)
+          })
+        }]
+      };
+    }
     const tryBuyResult = await publicClient.readContract({
       address: FOUR_MEME_HELPER_V3,
       abi: FOUR_MEME_HELPER_ABI,
@@ -1567,6 +1595,53 @@ server.tool(
       args: [tokenAddr, 0n, bnbAmount]
     });
     const [, , estimatedAmount, , estimatedFee, amountMsgValue] = tryBuyResult;
+    if (amountMsgValue < minTradingFee) {
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            status: "error",
+            message: "Computed payable amount is below Four.meme minimum trading fee threshold.",
+            next_step: "Increase amount and retry.",
+            token: tokenAddr,
+            payableWei: amountMsgValue.toString(),
+            minTradingFeeWei: minTradingFee.toString(),
+            minTradingFeeBnb: (Number(minTradingFee) / 1e18).toFixed(6)
+          })
+        }]
+      };
+    }
+    if (estimatedAmount <= 0n || amountMsgValue <= 0n) {
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            status: "error",
+            message: "four_buy quote returned zero output. Requested amount is likely too small for this market.",
+            next_step: "Increase amount and retry.",
+            token: tokenAddr
+          })
+        }]
+      };
+    }
+    const vaultBnbBalance = await publicClient.getBalance({ address: vault });
+    if (amountMsgValue > vaultBnbBalance) {
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            status: "error",
+            message: "Vault BNB balance is insufficient for four_buy.",
+            next_step: "Deposit more BNB to vault or reduce amount, then retry.",
+            vault,
+            requiredBnb: (Number(amountMsgValue) / 1e18).toFixed(6),
+            availableBnb: (Number(vaultBnbBalance) / 1e18).toFixed(6),
+            requiredWei: amountMsgValue.toString(),
+            availableWei: vaultBnbBalance.toString()
+          })
+        }]
+      };
+    }
     const minAmount = estimatedAmount * BigInt(100 - slippage) / 100n;
     const alignedMinAmount = minAmount / 1000000000n * 1000000000n;
     let data;
@@ -1578,7 +1653,23 @@ server.tool(
     const action = { target: tokenManager, value: amountMsgValue, data };
     const sim = await policyClient.validate(tokenId, action);
     if (!sim.ok) return { content: [{ type: "text", text: JSON.stringify({ status: "rejected", reason: sim.reason, ...policyRejectionHelp(sim.reason, token_id) }) }] };
-    const result = await policyClient.execute(tokenId, action, true);
+    let result;
+    try {
+      result = await policyClient.execute(tokenId, action, true);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown execution revert";
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            status: "error",
+            message: "four_buy execution reverted on-chain",
+            reason: message,
+            hint: "This is usually market-side failure (amount too small, temporary pool state change, or token-side constraint), not a PolicyGuard rejection."
+          })
+        }]
+      };
+    }
     return {
       content: [{
         type: "text",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "shll-skills",
-    "version": "5.5.1",
+    "version": "5.5.2",
     "description": "SHLL DeFi Agent — CLI + MCP Server for BSC",
     "main": "dist/index.js",
     "bin": {
@@ -24,4 +24,4 @@
         "tsup": "^8.0.2",
         "typescript": "^5.4.5"
     }
-}
+}

package/src/index.ts

@@ -2746,18 +2746,22 @@ fourBuyCmd.action(async (opts) => {
         const publicClient = createPublicClient({ chain: bsc, transport: http(rpcUrl) });
         const vault = await client.getVault(tokenId);
 
-        const tokenAddr = opts.token as Address;
-        const slippage = Number(opts.slippage);
-        const bnbAmount = parseAmount(opts.amount, 18);
-
-        // 1. Get token info to check status
-        const info = await publicClient.readContract({
-            address: FOUR_MEME_HELPER_V3,
-            abi: FOUR_MEME_HELPER_ABI,
+        const tokenAddr = opts.token as Address;
+        const slippage = Number(opts.slippage);
+        const bnbAmount = parseAmount(opts.amount, 18);
+        if (bnbAmount <= 0n) {
+            outputError("Invalid amount.", "four-buy amount must be a positive BNB value.");
+            process.exit(1);
+        }
+
+        // 1. Get token info to check status
+        const info = await publicClient.readContract({
+            address: FOUR_MEME_HELPER_V3,
+            abi: FOUR_MEME_HELPER_ABI,
             functionName: "getTokenInfo",
             args: [tokenAddr],
         });
-        const [version, tokenManager, quote, , , , , , , , , liquidityAdded] = info;
+        const [version, tokenManager, quote, , , minTradingFee, , , , , , liquidityAdded] = info;
 
         if (liquidityAdded) {
             output({ status: "error", message: "Token has already migrated to DEX. Use the 'swap' command instead of 'four-buy'." });
@@ -2765,19 +2769,75 @@ fourBuyCmd.action(async (opts) => {
         }
 
         const isQuoteBNB = quote === "0x0000000000000000000000000000000000000000";
-        if (!isQuoteBNB) {
-            output({ status: "error", message: `Token uses BEP20 quote (${quote}), not BNB. BEP20 quote pairs are not yet supported in this tool.` });
-            process.exit(1);
-        }
+        if (!isQuoteBNB) {
+            output({ status: "error", message: `Token uses BEP20 quote (${quote}), not BNB. BEP20 quote pairs are not yet supported in this tool.` });
+            process.exit(1);
+        }
+        if (bnbAmount < minTradingFee) {
+            outputError(
+                "Input amount is below Four.meme minimum trading fee threshold.",
+                "Increase --amount and retry.",
+                {
+                    token: tokenAddr,
+                    inputBnb: opts.amount,
+                    inputWei: bnbAmount.toString(),
+                    minTradingFeeWei: minTradingFee.toString(),
+                    minTradingFeeBnb: (Number(minTradingFee) / 1e18).toFixed(6),
+                },
+            );
+            process.exit(1);
+        }
 
         // 2. Pre-calculate buy estimate
-        const tryBuyResult = await publicClient.readContract({
-            address: FOUR_MEME_HELPER_V3,
-            abi: FOUR_MEME_HELPER_ABI,
-            functionName: "tryBuy",
-            args: [tokenAddr, 0n, bnbAmount],
-        });
-        const [, , estimatedAmount, estimatedCost, estimatedFee, amountMsgValue] = tryBuyResult;
+        const tryBuyResult = await publicClient.readContract({
+            address: FOUR_MEME_HELPER_V3,
+            abi: FOUR_MEME_HELPER_ABI,
+            functionName: "tryBuy",
+            args: [tokenAddr, 0n, bnbAmount],
+        });
+        const [, , estimatedAmount, estimatedCost, estimatedFee, amountMsgValue] = tryBuyResult;
+        if (amountMsgValue < minTradingFee) {
+            outputError(
+                "Computed payable amount is below Four.meme minimum trading fee threshold.",
+                "Increase --amount and retry.",
+                {
+                    token: tokenAddr,
+                    inputBnb: opts.amount,
+                    payableWei: amountMsgValue.toString(),
+                    minTradingFeeWei: minTradingFee.toString(),
+                    minTradingFeeBnb: (Number(minTradingFee) / 1e18).toFixed(6),
+                },
+            );
+            process.exit(1);
+        }
+        if (estimatedAmount <= 0n || amountMsgValue <= 0n) {
+            outputError(
+                "four-buy quote returned zero output.",
+                "Requested amount is likely too small for this market. Increase --amount and retry.",
+                {
+                    token: tokenAddr,
+                    inputBnb: opts.amount,
+                    estimatedCostWei: estimatedCost.toString(),
+                    estimatedFeeWei: estimatedFee.toString(),
+                },
+            );
+            process.exit(1);
+        }
+        const vaultBnbBalance = await publicClient.getBalance({ address: vault });
+        if (amountMsgValue > vaultBnbBalance) {
+            outputError(
+                "Vault BNB balance is insufficient for four-buy.",
+                "Deposit more BNB to vault or reduce --amount, then retry.",
+                {
+                    vault,
+                    requiredBnb: (Number(amountMsgValue) / 1e18).toFixed(6),
+                    availableBnb: (Number(vaultBnbBalance) / 1e18).toFixed(6),
+                    requiredWei: amountMsgValue.toString(),
+                    availableWei: vaultBnbBalance.toString(),
+                },
+            );
+            process.exit(1);
+        }
 
         // Align to GWEI precision (Four.meme requirement)
         const minAmount = (estimatedAmount * BigInt(100 - slippage)) / 100n;
@@ -2818,11 +2878,23 @@ fourBuyCmd.action(async (opts) => {
             process.exit(0);
         }
 
-        const result = await client.execute(tokenId, action, true);
-        output({
-            status: "success",
-            hash: result.hash,
-            protocol: "four.meme",
+        let result: { hash: Hex };
+        try {
+            result = await client.execute(tokenId, action, true);
+        } catch (error: unknown) {
+            const message = error instanceof Error ? error.message : "Unknown execution revert";
+            outputError(
+                "four-buy execution reverted on-chain.",
+                "Likely market-side failure (amount too small, temporary pool state change, or token-side constraint).",
+                { reason: message, token: tokenAddr, inputBnb: opts.amount },
+            );
+            process.exit(1);
+            return;
+        }
+        output({
+            status: "success",
+            hash: result.hash,
+            protocol: "four.meme",
             action: "buy",
             bnbSpent: opts.amount,
             estimatedTokens: (Number(estimatedAmount) / 1e18).toFixed(4),

package/src/mcp.ts

@@ -1730,39 +1730,109 @@ server.tool(
         amount: z.string().describe("BNB amount to spend (human-readable, e.g. 0.01)"),
         slippage: z.number().default(10).describe("Slippage tolerance percent (default: 10, meme tokens are volatile)"),
     },
-    async ({ token_id, token, amount, slippage }) => {
-        const { publicClient, policyClient } = createClients();
-        const tokenId = BigInt(token_id);
-        const expiryCheck = await checkAgentExpiry(tokenId);
-        if (expiryCheck.blocked) return { content: expiryCheck.content! };
-
-        const tokenAddr = token as Address;
-        const bnbAmount = parseAmount(amount, 18);
-
-        // 1. Get token info
-        const info = await publicClient.readContract({
-            address: FOUR_MEME_HELPER_V3,
-            abi: FOUR_MEME_HELPER_ABI,
+    async ({ token_id, token, amount, slippage }) => {
+        const { publicClient, policyClient } = createClients();
+        const tokenId = BigInt(token_id);
+        const expiryCheck = await checkAgentExpiry(tokenId);
+        if (expiryCheck.blocked) return { content: expiryCheck.content! };
+
+        const tokenAddr = token as Address;
+        const bnbAmount = parseAmount(amount, 18);
+        if (bnbAmount <= 0n) {
+            return {
+                content: [{
+                    type: "text" as const, text: JSON.stringify({
+                        status: "error",
+                        message: "Invalid amount. four_buy amount must be a positive BNB value.",
+                    })
+                }],
+            };
+        }
+        const vault = await policyClient.getVault(tokenId);
+
+        // 1. Get token info
+        const info = await publicClient.readContract({
+            address: FOUR_MEME_HELPER_V3,
+            abi: FOUR_MEME_HELPER_ABI,
             functionName: "getTokenInfo",
             args: [tokenAddr],
         });
-        const [version, tokenManager, quote, , , , , , , , , liquidityAdded] = info;
+        const [version, tokenManager, quote, , , minTradingFee, , , , , , liquidityAdded] = info;
 
         if (liquidityAdded) {
             return { content: [{ type: "text" as const, text: JSON.stringify({ status: "error", message: "Token has already migrated to DEX. Use the 'swap' tool instead." }) }] };
         }
-        if (quote !== "0x0000000000000000000000000000000000000000") {
-            return { content: [{ type: "text" as const, text: JSON.stringify({ status: "error", message: `Token uses BEP20 quote (${quote}), not BNB. BEP20 pairs not yet supported.` }) }] };
-        }
+        if (quote !== "0x0000000000000000000000000000000000000000") {
+            return { content: [{ type: "text" as const, text: JSON.stringify({ status: "error", message: `Token uses BEP20 quote (${quote}), not BNB. BEP20 pairs not yet supported.` }) }] };
+        }
+        if (bnbAmount < minTradingFee) {
+            return {
+                content: [{
+                    type: "text" as const, text: JSON.stringify({
+                        status: "error",
+                        message: "Input amount is below Four.meme minimum trading fee threshold.",
+                        next_step: "Increase amount and retry.",
+                        token: tokenAddr,
+                        inputWei: bnbAmount.toString(),
+                        minTradingFeeWei: minTradingFee.toString(),
+                        minTradingFeeBnb: (Number(minTradingFee) / 1e18).toFixed(6),
+                    })
+                }],
+            };
+        }
 
         // 2. Pre-calculate
-        const tryBuyResult = await publicClient.readContract({
-            address: FOUR_MEME_HELPER_V3,
-            abi: FOUR_MEME_HELPER_ABI,
-            functionName: "tryBuy",
-            args: [tokenAddr, 0n, bnbAmount],
-        });
-        const [, , estimatedAmount, , estimatedFee, amountMsgValue] = tryBuyResult;
+        const tryBuyResult = await publicClient.readContract({
+            address: FOUR_MEME_HELPER_V3,
+            abi: FOUR_MEME_HELPER_ABI,
+            functionName: "tryBuy",
+            args: [tokenAddr, 0n, bnbAmount],
+        });
+        const [, , estimatedAmount, , estimatedFee, amountMsgValue] = tryBuyResult;
+        if (amountMsgValue < minTradingFee) {
+            return {
+                content: [{
+                    type: "text" as const, text: JSON.stringify({
+                        status: "error",
+                        message: "Computed payable amount is below Four.meme minimum trading fee threshold.",
+                        next_step: "Increase amount and retry.",
+                        token: tokenAddr,
+                        payableWei: amountMsgValue.toString(),
+                        minTradingFeeWei: minTradingFee.toString(),
+                        minTradingFeeBnb: (Number(minTradingFee) / 1e18).toFixed(6),
+                    })
+                }],
+            };
+        }
+        if (estimatedAmount <= 0n || amountMsgValue <= 0n) {
+            return {
+                content: [{
+                    type: "text" as const, text: JSON.stringify({
+                        status: "error",
+                        message: "four_buy quote returned zero output. Requested amount is likely too small for this market.",
+                        next_step: "Increase amount and retry.",
+                        token: tokenAddr,
+                    })
+                }],
+            };
+        }
+        const vaultBnbBalance = await publicClient.getBalance({ address: vault });
+        if (amountMsgValue > vaultBnbBalance) {
+            return {
+                content: [{
+                    type: "text" as const, text: JSON.stringify({
+                        status: "error",
+                        message: "Vault BNB balance is insufficient for four_buy.",
+                        next_step: "Deposit more BNB to vault or reduce amount, then retry.",
+                        vault,
+                        requiredBnb: (Number(amountMsgValue) / 1e18).toFixed(6),
+                        availableBnb: (Number(vaultBnbBalance) / 1e18).toFixed(6),
+                        requiredWei: amountMsgValue.toString(),
+                        availableWei: vaultBnbBalance.toString(),
+                    })
+                }],
+            };
+        }
 
         // Align to GWEI precision (Four.meme requirement)
         const minAmount = (estimatedAmount * BigInt(100 - slippage)) / 100n;
@@ -1781,11 +1851,26 @@ server.tool(
         const sim = await policyClient.validate(tokenId, action);
         if (!sim.ok) return { content: [{ type: "text" as const, text: JSON.stringify({ status: "rejected", reason: sim.reason, ...policyRejectionHelp(sim.reason, token_id) }) }] };
 
-        const result = await policyClient.execute(tokenId, action, true);
-        return {
-            content: [{
-                type: "text" as const, text: JSON.stringify({
-                    status: "success", hash: result.hash, protocol: "four.meme", action: "buy",
+        let result: { hash: Hex };
+        try {
+            result = await policyClient.execute(tokenId, action, true);
+        } catch (error: unknown) {
+            const message = error instanceof Error ? error.message : "Unknown execution revert";
+            return {
+                content: [{
+                    type: "text" as const, text: JSON.stringify({
+                        status: "error",
+                        message: "four_buy execution reverted on-chain",
+                        reason: message,
+                        hint: "This is usually market-side failure (amount too small, temporary pool state change, or token-side constraint), not a PolicyGuard rejection.",
+                    })
+                }],
+            };
+        }
+        return {
+            content: [{
+                type: "text" as const, text: JSON.stringify({
+                    status: "success", hash: result.hash, protocol: "four.meme", action: "buy",
                     bnbSpent: amount,
                     estimatedTokens: (Number(estimatedAmount) / 1e18).toFixed(4),
                     fee: (Number(estimatedFee) / 1e18).toFixed(6),