@michaleffffff/mcp-trading-server 3.0.15 → 3.0.20

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 3.0.20 - 2026-03-19
+
+### Fixed
+- Hardened `get_pool_metadata` funding-rate formatting:
+  - `fundingInfo.nextFundingRate` now preserves readable `%/秒` and `%/天` output for negative rates too.
+  - Regression coverage now asserts both numeric funding-rate views and display strings.
+
+## 3.0.19 - 2026-03-19
+
+### Fixed
+- Refined `fundingInfo.nextFundingRate` formatting in `get_pool_metadata`:
+  - Displays percent per second as `%/秒`
+  - Displays derived percent per day as `%/天`
+  - Keeps raw integer and comma-separated views for audit/debug use
+
+## 3.0.18 - 2026-03-19
+
+### Fixed
+- Further improved `fundingInfo` / `ioTracker` readability in `get_pool_metadata`:
+  - `fundingInfo.nextEpochTime` now includes UTC timestamp and seconds-until-next-epoch.
+  - `fundingInfo.nextFundingRate` and `lastFundingFeeTracker` now include comma-separated raw views.
+  - `ioTracker` now includes derived notional-at-entry views based on `poolEntryPrice`.
+
+## 3.0.17 - 2026-03-19
+
+### Fixed
+- Improved precision handling for liquidity and pool read tools:
+  - `get_pool_metadata` now adds `poolInfoFormatted` for exchange rate, LP token price, LP supply, debt, collateral, reserves, and open interest.
+  - `get_lp_price` now returns both raw and human-readable formatted values.
+  - Added regression coverage to ensure formatted precision fields are present.
+
+## 3.0.16 - 2026-03-18
+
+### Fixed
+- Improved MCP-side validation UX:
+  - `executionFeeToken` now fails early with a clear `INVALID_PARAM` when callers pass the zero address, and points users to the real pool `quoteToken`.
+  - `open_position_simple` no longer returns a generic numeric parse error when `collateralAmount` is omitted; it now explains that `collateralAmount` is still required and suggests an approximate value from `size`, `price`, and `leverage`.
+
 ## 3.0.15 - 2026-03-18
 
 ### Fixed

package/README.md

@@ -6,7 +6,7 @@ A production-ready MCP (Model Context Protocol) server for deep integration with
 
 # Release Notes
 
-- **Current release: 3.0.15**
+- **Current release: 3.0.20**
 - **SDK baseline**: `@myx-trade/sdk@^1.0.2` compatibility completed.
 - **Refinement**: Consolidated 40+ specialized tools into ~26 high-level unified tools.
 - **Improved UX**: Enhanced AI parameter parsing, automated unit conversion, and structured error reporting.
@@ -20,6 +20,7 @@ A production-ready MCP (Model Context Protocol) server for deep integration with
 * **AI-First Design**: Automated Pool ID resolution and flexible unit handling (`human:` vs `raw:`).
 * **Deep Liquidity Support**: Tools for both traders and liquidity providers.
 * **Production Ready**: Robust error handling with actionable hints for LLMs.
+* **Precision-Aware Reads**: Pool and LP read tools expose human-readable formatted values alongside raw on-chain integers.
 * **Compliant**: Full Model Context Protocol (MCP) support.
 
 ---
@@ -109,6 +110,7 @@ Use these conventions when generating tool arguments:
 - `orderType`: `MARKET` / `LIMIT` / `STOP` / `CONDITIONAL`
 - `timeInForce`: SDK `v1.0.2` currently supports `IOC` only, so use `0` or `"IOC"`
 - `size`: base token quantity, not USD notional; expected order value is usually `collateralAmount * leverage`
+- `executionFeeToken`: must be a real token address; zero address is rejected. Use the pool `quoteToken`
 - Human units: `"100"` means 100 USDC or 100 token units depending on field
 - Raw units: `"raw:1000000"` means exact on-chain integer units
 

package/TOOL_EXAMPLES.md

@@ -1,4 +1,4 @@
-# MYX MCP Tool Examples Handbook (v3.0.15)
+# MYX MCP Tool Examples Handbook (v3.0.20)
 
 This guide provides practical MCP payload examples for the current unified toolset.
 All examples use the MCP format:
@@ -74,6 +74,7 @@ Recommended high-level entry tool.
 
 `marketId` is optional on `open_position_simple`. If supplied, it is validated against the market resolved from `poolId` or `keyword`.
 `size` is always the base-asset quantity, not the USD notional. For example, a 500 USD order at price 1200 implies `size ≈ 0.416666...`.
+`collateralAmount` remains required on `open_position_simple`; if omitted, MCP now returns an actionable suggestion instead of a generic parse error.
 
 Raw-units example:
 
@@ -111,6 +112,7 @@ Low-level increase-order tool when you want full control.
 ```
 
 `timeInForce` should be `0` (or `"IOC"` in string form) for SDK `v1.0.2`.
+`executionFeeToken` must be a real token address; do not pass the zero address. Use the pool `quoteToken`.
 
 ### `close_position`
 Close or reduce a position. Use `ALL` for a full close.
@@ -231,6 +233,8 @@ Unified pool detail, config, and liquidity info.
 }
 ```
 
+`get_pool_metadata` returns raw values in `poolInfo` and precision-safe human-readable values in `poolInfoFormatted`, including readable funding epoch timestamps, funding-rate `%/秒` and `%/天`, and IO notional-at-entry views.
+
 ### `get_kline`
 Read chart data. Use `limit: 1` for the latest bar.
 
@@ -293,6 +297,8 @@ Read LP NAV price for BASE or QUOTE side.
 }
 ```
 
+`get_lp_price` returns both `raw` and `formatted` NAV price values.
+
 ### `get_my_lp_holdings`
 Read current LP balances across pools.
 

package/dist/server.js

@@ -39,7 +39,7 @@ function safeJsonStringify(value) {
 }
 function inferToolErrorCode(message) {
     const lower = message.toLowerCase();
-    if (lower.includes("required") || lower.includes("invalid") || lower.includes("must be") || lower.includes("unexpected") || lower.includes("unrecognized")) {
+    if (lower.includes("required") || lower.includes("invalid") || lower.includes("must be") || lower.includes("unexpected") || lower.includes("unrecognized") || lower.includes("zero address")) {
         return "INVALID_PARAM";
     }
     if (lower.includes("insufficient") && (lower.includes("allowance") || lower.includes("approval"))) {
@@ -461,7 +461,7 @@ function zodSchemaToJsonSchema(zodSchema) {
     };
 }
 // ─── MCP Server ───
-const server = new Server({ name: "myx-mcp-trading-server", version: "3.0.15" }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
+const server = new Server({ name: "myx-mcp-trading-server", version: "3.0.20" }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
 // List tools
 server.setRequestHandler(ListToolsRequestSchema, async () => {
     return {
@@ -582,7 +582,7 @@ server.setRequestHandler(GetPromptRequestSchema, async (request) => {
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    logger.info("🚀 MYX Trading MCP Server v3.0.15 running (stdio, pure on-chain, prod ready)");
+    logger.info("🚀 MYX Trading MCP Server v3.0.20 running (stdio, pure on-chain, prod ready)");
 }
 main().catch((err) => {
     logger.error("Fatal Server Startup Error", err);

package/dist/tools/executeTrade.js

@@ -7,6 +7,7 @@ import { verifyTradeOutcome } from "../utils/verification.js";
 import { mapDirection, mapOrderType, mapTriggerType } from "../utils/mappings.js";
 import { extractErrorMessage } from "../utils/errorMessage.js";
 import { parseUserUnits } from "../utils/units.js";
+import { isZeroAddress } from "../utils/address.js";
 const POSITION_ID_RE = /^$|^0x[0-9a-fA-F]{64}$/;
 const ZERO_POSITION_ID_RE = /^0x0{64}$/i;
 export const executeTradeTool = {
@@ -61,6 +62,11 @@ export const executeTradeTool = {
             const mappedOrderType = mapOrderType(args.orderType);
             const mappedTriggerType = args.triggerType !== undefined ? mapTriggerType(args.triggerType) : undefined;
             const slippagePctNormalized = normalizeSlippagePct4dp(args.slippagePct);
+            if (args.executionFeeToken !== undefined && args.executionFeeToken !== null && String(args.executionFeeToken).trim() !== "") {
+                if (isZeroAddress(args.executionFeeToken)) {
+                    throw new Error(`executionFeeToken cannot be zero address. Use the pool quoteToken address ${poolData.quoteToken}.`);
+                }
+            }
             const collateralRaw = parseUserUnits(args.collateralAmount, quoteDecimals, "collateralAmount");
             const sizeRaw = parseUserUnits(args.size, baseDecimals, "size");
             const priceRaw = parseUserUnits(args.price, 30, "price");

package/dist/tools/getPoolMetadata.js

@@ -1,10 +1,12 @@
 import { z } from "zod";
+import { formatUnits } from "ethers";
 import { resolveClient, getChainId } from "../auth/resolveClient.js";
 import { getMarketDetail, resolvePool } from "../services/marketService.js";
 import { getPoolInfo, getLiquidityInfo } from "../services/poolService.js";
 import { extractErrorMessage } from "../utils/errorMessage.js";
 import { parseUserPrice30 } from "../utils/units.js";
 const INTEGER_RE = /^\d+$/;
+const SIGNED_INTEGER_RE = /^-?\d+$/;
 const DECIMAL_RE = /^\d+(\.\d+)?$/;
 function normalizeMarketPrice30Input(value) {
     const text = String(value ?? "").trim();
@@ -29,6 +31,180 @@ function compactWarning(scope, err) {
     }
     return `${scope}: ${flat}`;
 }
+function formatRawValue(value, decimals) {
+    const text = String(value ?? "").trim();
+    if (!INTEGER_RE.test(text))
+        return null;
+    try {
+        return formatUnits(text, decimals);
+    }
+    catch {
+        return null;
+    }
+}
+function buildFormattedAmount(value, decimals, symbol) {
+    const raw = String(value ?? "");
+    const formatted = formatRawValue(value, decimals);
+    return {
+        raw,
+        decimals,
+        formatted,
+        display: formatted && symbol ? `${formatted} ${symbol}` : formatted,
+        symbol: symbol ?? null,
+    };
+}
+function buildFormattedPrice30(value, quoteSymbol) {
+    const raw = String(value ?? "");
+    const formatted = formatRawValue(value, 30);
+    return {
+        raw,
+        decimals: 30,
+        formatted,
+        display: formatted && quoteSymbol ? `${formatted} ${quoteSymbol}` : formatted,
+        symbol: quoteSymbol ?? null,
+    };
+}
+function buildFormattedRatio18(value) {
+    const raw = String(value ?? "");
+    const formatted = formatRawValue(value, 18);
+    return {
+        raw,
+        decimals: 18,
+        formatted,
+        display: formatted,
+    };
+}
+function buildRawScalar(value) {
+    const raw = String(value ?? "").trim();
+    if (!SIGNED_INTEGER_RE.test(raw)) {
+        return { raw, withCommas: raw || null };
+    }
+    try {
+        return {
+            raw,
+            withCommas: BigInt(raw).toLocaleString("en-US"),
+        };
+    }
+    catch {
+        return { raw, withCommas: raw };
+    }
+}
+function formatScaledIntegerString(raw, decimals) {
+    if (!SIGNED_INTEGER_RE.test(raw))
+        return null;
+    const negative = raw.startsWith("-");
+    const digits = negative ? raw.slice(1) : raw;
+    const padded = digits.padStart(decimals + 1, "0");
+    const intPart = padded.slice(0, -decimals) || "0";
+    const fracPart = padded.slice(-decimals).replace(/0+$/, "");
+    const normalized = fracPart ? `${intPart}.${fracPart}` : intPart;
+    return negative ? `-${normalized}` : normalized;
+}
+function buildFundingRateInfo(value) {
+    const base = buildRawScalar(value);
+    const raw = String(value ?? "").trim();
+    if (!SIGNED_INTEGER_RE.test(raw))
+        return base;
+    try {
+        const rawBig = BigInt(raw);
+        const perDayRaw = rawBig * 86400n;
+        const percentPerSecond = formatScaledIntegerString(raw, 12);
+        const percentPerDay = formatScaledIntegerString(perDayRaw.toString(), 12);
+        return {
+            ...base,
+            scale: "1e12 => percent",
+            percentPerSecond,
+            displayPerSecond: percentPerSecond ? `${percentPerSecond}%/秒` : null,
+            percentPerDay,
+            displayPerDay: percentPerDay ? `${percentPerDay}%/天` : null,
+        };
+    }
+    catch {
+        return base;
+    }
+}
+function buildTimestampInfo(value) {
+    const raw = String(value ?? "").trim();
+    const base = buildRawScalar(value);
+    if (!INTEGER_RE.test(raw)) {
+        return base;
+    }
+    const seconds = Number(raw);
+    if (!Number.isFinite(seconds) || seconds <= 0) {
+        return base;
+    }
+    const isoUtc = new Date(seconds * 1000).toISOString();
+    const secondsUntil = seconds - Math.floor(Date.now() / 1000);
+    return {
+        ...base,
+        isoUtc,
+        secondsUntil,
+    };
+}
+function computeQuoteNotionalDisplay(baseRaw, price30Raw, baseDecimals, quoteDecimals, quoteSymbol) {
+    const baseText = String(baseRaw ?? "").trim();
+    const priceText = String(price30Raw ?? "").trim();
+    if (!INTEGER_RE.test(baseText) || !INTEGER_RE.test(priceText))
+        return null;
+    try {
+        const notionalRaw = (BigInt(baseText) * BigInt(priceText) * (10n ** BigInt(quoteDecimals))) /
+            (10n ** BigInt(baseDecimals + 30));
+        return buildFormattedAmount(notionalRaw.toString(), quoteDecimals, quoteSymbol);
+    }
+    catch {
+        return null;
+    }
+}
+function formatPoolInfoSnapshot(poolInfo, marketDetail) {
+    if (!poolInfo || typeof poolInfo !== "object")
+        return null;
+    const baseSymbol = String(marketDetail?.baseSymbol ?? "BASE");
+    const quoteSymbol = String(marketDetail?.quoteSymbol ?? "QUOTE");
+    const baseDecimals = Number(marketDetail?.baseDecimals ?? 18);
+    const quoteDecimals = Number(marketDetail?.quoteDecimals ?? 6);
+    return {
+        quotePool: poolInfo.quotePool ? {
+            poolToken: poolInfo.quotePool.poolToken ?? null,
+            exchangeRate: buildFormattedRatio18(poolInfo.quotePool.exchangeRate),
+            poolTokenPrice: buildFormattedPrice30(poolInfo.quotePool.poolTokenPrice, quoteSymbol),
+            poolTokenSupply: buildFormattedAmount(poolInfo.quotePool.poolTokenSupply, 18, `m${quoteSymbol}.${baseSymbol}`),
+            totalDebt: buildFormattedAmount(poolInfo.quotePool.totalDebt, quoteDecimals, quoteSymbol),
+            baseCollateral: buildFormattedAmount(poolInfo.quotePool.baseCollateral, baseDecimals, baseSymbol),
+        } : null,
+        basePool: poolInfo.basePool ? {
+            poolToken: poolInfo.basePool.poolToken ?? null,
+            exchangeRate: buildFormattedRatio18(poolInfo.basePool.exchangeRate),
+            poolTokenPrice: buildFormattedPrice30(poolInfo.basePool.poolTokenPrice, quoteSymbol),
+            poolTokenSupply: buildFormattedAmount(poolInfo.basePool.poolTokenSupply, 18, `m${baseSymbol}.${quoteSymbol}`),
+            totalDebt: buildFormattedAmount(poolInfo.basePool.totalDebt, quoteDecimals, quoteSymbol),
+            baseCollateral: buildFormattedAmount(poolInfo.basePool.baseCollateral, baseDecimals, baseSymbol),
+        } : null,
+        reserveInfo: poolInfo.reserveInfo ? {
+            baseTotalAmount: buildFormattedAmount(poolInfo.reserveInfo.baseTotalAmount, baseDecimals, baseSymbol),
+            baseReservedAmount: buildFormattedAmount(poolInfo.reserveInfo.baseReservedAmount, baseDecimals, baseSymbol),
+            quoteTotalAmount: buildFormattedAmount(poolInfo.reserveInfo.quoteTotalAmount, quoteDecimals, quoteSymbol),
+            quoteReservedAmount: buildFormattedAmount(poolInfo.reserveInfo.quoteReservedAmount, quoteDecimals, quoteSymbol),
+        } : null,
+        fundingInfo: poolInfo.fundingInfo ? {
+            nextFundingRate: buildFundingRateInfo(poolInfo.fundingInfo.nextFundingRate),
+            lastFundingFeeTracker: buildRawScalar(poolInfo.fundingInfo.lastFundingFeeTracker),
+            nextEpochTime: buildTimestampInfo(poolInfo.fundingInfo.nextEpochTime),
+        } : null,
+        ioTracker: poolInfo.ioTracker ? {
+            tracker: buildFormattedAmount(poolInfo.ioTracker.tracker, baseDecimals, baseSymbol),
+            longSize: buildFormattedAmount(poolInfo.ioTracker.longSize, baseDecimals, baseSymbol),
+            shortSize: buildFormattedAmount(poolInfo.ioTracker.shortSize, baseDecimals, baseSymbol),
+            poolEntryPrice: buildFormattedPrice30(poolInfo.ioTracker.poolEntryPrice, quoteSymbol),
+            trackerNotionalAtEntry: computeQuoteNotionalDisplay(poolInfo.ioTracker.tracker, poolInfo.ioTracker.poolEntryPrice, baseDecimals, quoteDecimals, quoteSymbol),
+            longNotionalAtEntry: computeQuoteNotionalDisplay(poolInfo.ioTracker.longSize, poolInfo.ioTracker.poolEntryPrice, baseDecimals, quoteDecimals, quoteSymbol),
+            shortNotionalAtEntry: computeQuoteNotionalDisplay(poolInfo.ioTracker.shortSize, poolInfo.ioTracker.poolEntryPrice, baseDecimals, quoteDecimals, quoteSymbol),
+        } : null,
+        liquidityInfo: poolInfo.liquidityInfo ? {
+            windowCaps: buildFormattedAmount(poolInfo.liquidityInfo.windowCaps, quoteDecimals, quoteSymbol),
+            openInterest: buildFormattedAmount(poolInfo.liquidityInfo.openInterest, 18, quoteSymbol),
+        } : null,
+    };
+}
 export const getPoolMetadataTool = {
     name: "get_pool_metadata",
     description: "[MARKET] Get comprehensive metadata for a pool (market detail, on-chain info, liquidity, and limits).",
@@ -57,6 +233,11 @@ export const getPoolMetadataTool = {
             // 2. Pool Info (Reserves, Utilization)
             try {
                 results.poolInfo = await getPoolInfo(poolId, chainId, client);
+                const rawMarketDetail = results.marketDetail?.data ?? results.marketDetail;
+                const formatted = formatPoolInfoSnapshot(results.poolInfo, rawMarketDetail);
+                if (formatted) {
+                    results.poolInfoFormatted = formatted;
+                }
             }
             catch (err) {
                 errors.push(compactWarning("poolInfo", err));

package/dist/tools/manageLiquidity.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { formatUnits } from "ethers";
 import { quoteDeposit, quoteWithdraw, baseDeposit, baseWithdraw, getLpPrice, } from "../services/poolService.js";
 import { resolveClient, getChainId } from "../auth/resolveClient.js";
 import { resolvePool } from "../services/marketService.js";
@@ -45,6 +46,20 @@ function resolveLpAssetNames(detail) {
         quoteLpAssetName,
     };
 }
+function formatLpPricePayload(value, quoteSymbol) {
+    const raw = String(value ?? "").trim();
+    if (!/^\d+$/.test(raw)) {
+        return { raw, formatted: null, decimals: 30, symbol: quoteSymbol ?? null };
+    }
+    const formatted = formatUnits(raw, 30);
+    return {
+        raw,
+        formatted,
+        decimals: 30,
+        symbol: quoteSymbol ?? null,
+        display: quoteSymbol ? `${formatted} ${quoteSymbol}` : formatted,
+    };
+}
 export const manageLiquidityTool = {
     name: "manage_liquidity",
     description: "[LIQUIDITY] Add or withdraw liquidity from a BASE or QUOTE pool. Success response includes LP naming metadata: base `mBASE.QUOTE`, quote `mQUOTE.BASE`, plus `operatedLpAssetName` based on poolType.",
@@ -135,8 +150,20 @@ export const getLpPriceTool = {
     },
     handler: async (args) => {
         try {
-            const data = await getLpPrice(args.poolType, args.poolId, args.chainId);
-            return { content: [{ type: "text", text: JSON.stringify({ status: "success", data }, (k, v) => typeof v === 'bigint' ? v.toString() : v, 2) }] };
+            const { client } = await resolveClient();
+            const chainId = args.chainId ?? getChainId();
+            const poolId = await resolvePool(client, args.poolId, undefined, chainId);
+            const detailRes = await client.markets.getMarketDetail({ chainId, poolId }).catch(() => null);
+            const detail = detailRes?.data || (detailRes?.marketId ? detailRes : null);
+            const quoteSymbol = String(detail?.quoteSymbol ?? "").trim() || null;
+            const rawPrice = await getLpPrice(args.poolType, poolId, chainId);
+            const payload = {
+                raw: String(rawPrice ?? ""),
+                formatted: formatLpPricePayload(rawPrice, quoteSymbol ?? undefined),
+                poolType: args.poolType,
+                poolId,
+            };
+            return { content: [{ type: "text", text: JSON.stringify({ status: "success", data: payload }, (k, v) => typeof v === 'bigint' ? v.toString() : v, 2) }] };
         }
         catch (error) {
             return { content: [{ type: "text", text: `Error: ${extractErrorMessage(error)}` }], isError: true };

package/dist/tools/openPositionSimple.js

@@ -1,9 +1,10 @@
 import { z } from "zod";
 import { OrderType } from "@myx-trade/sdk";
+import { formatUnits } from "ethers";
 import { resolveClient, getChainId } from "../auth/resolveClient.js";
 import { resolvePool } from "../services/marketService.js";
 import { openPosition } from "../services/tradeService.js";
-import { normalizeAddress } from "../utils/address.js";
+import { isZeroAddress, normalizeAddress } from "../utils/address.js";
 import { finalizeMutationResult } from "../utils/mutationResult.js";
 import { mapDirection, mapOrderType } from "../utils/mappings.js";
 import { normalizeSlippagePct4dp, SLIPPAGE_PCT_4DP_DESC } from "../utils/slippage.js";
@@ -43,6 +44,7 @@ export const openPositionSimpleTool = {
         direction: z.any().describe("0=LONG, 1=SHORT, or strings like 'BUY'/'SELL'/'LONG'/'SHORT'."),
         collateralAmount: z.coerce
             .string()
+            .optional()
             .describe("Collateral. e.g. '100' (quoted in USDC) or 'raw:100000000'."),
         leverage: z.coerce.number().int().positive().describe("Leverage (integer, e.g. 5, 10)."),
         orderType: z.union([z.string(), z.number()]).optional().describe("MARKET, LIMIT, STOP (default MARKET). Strings allowed."),
@@ -113,21 +115,14 @@ export const openPositionSimpleTool = {
             const defaultAssetClass = Number(poolLevelConfig?.levelConfig?.assetClass ?? 0);
             // 3) Parse & validate primary inputs
             const dir = mapDirection(args.direction);
-            const collateralRaw = parseUserUnits(args.collateralAmount, quoteDecimals, "collateralAmount");
-            const collateralRawBig = asBigint(collateralRaw, "collateralAmount");
-            if (collateralRawBig <= 0n)
-                throw new Error("collateralAmount must be > 0.");
-            const maxTradeAmountHuman = String(process.env.MAX_TRADE_AMOUNT ?? "").trim();
-            if (maxTradeAmountHuman) {
-                const maxTradeRaw = parseUserUnits(maxTradeAmountHuman, quoteDecimals, "MAX_TRADE_AMOUNT");
-                const maxTradeRawBig = asBigint(maxTradeRaw, "MAX_TRADE_AMOUNT");
-                if (collateralRawBig > maxTradeRawBig) {
-                    throw new Error(`collateralAmount exceeds MAX_TRADE_AMOUNT (collateralRaw=${collateralRawBig.toString()} > maxRaw=${maxTradeRawBig.toString()}).`);
-                }
-            }
             const orderType = mapOrderType(args.orderType ?? 0);
             const postOnly = Boolean(args.postOnly ?? false);
             const slippagePct = normalizeSlippagePct4dp(args.slippagePct ?? "50");
+            if (args.executionFeeToken !== undefined && args.executionFeeToken !== null && String(args.executionFeeToken).trim() !== "") {
+                if (isZeroAddress(args.executionFeeToken)) {
+                    throw new Error(`executionFeeToken cannot be zero address. Use the pool quoteToken address ${quoteToken}.`);
+                }
+            }
             const executionFeeToken = normalizeAddress(args.executionFeeToken || quoteToken, "executionFeeToken");
             // 4) Determine reference price (30 decimals)
             let price30;
@@ -157,6 +152,15 @@ export const openPositionSimpleTool = {
             const price30Big = asBigint(price30, "price");
             if (price30Big <= 0n)
                 throw new Error("price must be > 0.");
+            const collateralInput = String(args.collateralAmount ?? "").trim();
+            let collateralRaw = "";
+            let collateralRawBig = 0n;
+            if (collateralInput) {
+                collateralRaw = parseUserUnits(collateralInput, quoteDecimals, "collateralAmount");
+                collateralRawBig = asBigint(collateralRaw, "collateralAmount");
+                if (collateralRawBig <= 0n)
+                    throw new Error("collateralAmount must be > 0.");
+            }
             // 5) Compute or parse size (base raw units)
             let sizeRaw = "";
             let sizeMeta = { source: "computed" };
@@ -166,6 +170,9 @@ export const openPositionSimpleTool = {
                 sizeMeta = { source: "user" };
             }
             else {
+                if (!collateralInput) {
+                    throw new Error("Either collateralAmount or size is required for open_position_simple.");
+                }
                 const notionalQuoteRaw = collateralRawBig * BigInt(args.leverage);
                 const numerator = notionalQuoteRaw * pow10(30 + baseDecimals);
                 const denominator = price30Big * pow10(quoteDecimals);
@@ -176,6 +183,22 @@ export const openPositionSimpleTool = {
                 sizeRaw = computed.toString();
                 sizeMeta = { source: "computed", notionalQuoteRaw: notionalQuoteRaw.toString() };
             }
+            const sizeRawBig = asBigint(sizeRaw, "size");
+            if (!collateralInput) {
+                const notionalQuoteRaw = (sizeRawBig * price30Big * pow10(quoteDecimals)) / pow10(baseDecimals + 30);
+                const suggestedCollateralRaw = notionalQuoteRaw / BigInt(args.leverage);
+                const suggestedCollateralHuman = formatUnits(suggestedCollateralRaw, quoteDecimals);
+                const notionalHuman = formatUnits(notionalQuoteRaw, quoteDecimals);
+                throw new Error(`collateralAmount is required for open_position_simple. Based on size=${userSize || formatUnits(sizeRawBig, baseDecimals)}, price=${priceMeta.human ?? formatUnits(price30Big, 30)}, leverage=${args.leverage}, implied order value is ≈${notionalHuman} quote and suggested collateralAmount is ≈${suggestedCollateralHuman}.`);
+            }
+            const maxTradeAmountHuman = String(process.env.MAX_TRADE_AMOUNT ?? "").trim();
+            if (maxTradeAmountHuman) {
+                const maxTradeRaw = parseUserUnits(maxTradeAmountHuman, quoteDecimals, "MAX_TRADE_AMOUNT");
+                const maxTradeRawBig = asBigint(maxTradeRaw, "MAX_TRADE_AMOUNT");
+                if (collateralRawBig > maxTradeRawBig) {
+                    throw new Error(`collateralAmount exceeds MAX_TRADE_AMOUNT (collateralRaw=${collateralRawBig.toString()} > maxRaw=${maxTradeRawBig.toString()}).`);
+                }
+            }
             // 6) Compute tradingFee (quote raw units)
             let tradingFeeRaw = null;
             let tradingFeeMeta = { source: "computed" };

package/dist/utils/address.js

@@ -1,4 +1,5 @@
 import { getAddress } from "ethers";
+export const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
 export function normalizeAddress(value, label = "address") {
     const raw = String(value || "").trim();
     if (!raw)
@@ -15,3 +16,14 @@ export function normalizeAddress(value, label = "address") {
         }
     }
 }
+export function isZeroAddress(value) {
+    const raw = String(value ?? "").trim();
+    if (!raw)
+        return false;
+    try {
+        return getAddress(raw).toLowerCase() === ZERO_ADDRESS;
+    }
+    catch {
+        return raw.toLowerCase() === ZERO_ADDRESS;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@michaleffffff/mcp-trading-server",
-  "version": "3.0.15",
+  "version": "3.0.20",
   "type": "module",
   "bin": {
     "myx-mcp": "dist/server.js"