@michaleffffff/mcp-trading-server 3.0.1 → 3.0.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 3.0.2 - 2026-03-17
+
+### Added
+- Integrated `verifyTradeOutcome` in `execute_trade` for post-transaction state validation.
+- Automatic `tradingFee` calculation in `execute_trade` using `getUserTradingFeeRate`.
+- `parseUserUnits` / `parseUserPrice30` utilities for more consistent human/raw input handling.
+
+### Changed
+- `execute_trade` now surfaces `preflight` normalization details in the successful response.
+- `adjust_margin` now supports displaying `__normalized` data.
+- Refined unit resolution in `account_deposit` and `account_withdraw`.
+
 ## 3.0.1 - 2026-03-17
 
 ### Added

package/README.md

@@ -291,7 +291,7 @@ For practical tool-by-tool examples, see: `TOOL_EXAMPLES.md`
 
 ### Trading Operations
 * **open_position_simple**: High-level open position helper (recommended). Computes price/size/tradingFee internally.
-* **execute_trade**: Execute a new trade or add to an existing position.
+* **execute_trade**: Execute a new trade or add to an existing position (includes parameter preflight, supports `human:`/`raw:` amount prefixes, auto-computes `tradingFee` when omitted).
 * **close_position**: Close an open position.
 * **close_all_positions**: Emergency: close ALL open positions in a pool at once.
 * **cancel_order**: Cancel an open order by its order ID.
@@ -377,6 +377,12 @@ Use this query/mutation loop for limit-order management:
 4. Check historical fills/cancellations with `get_order_history`.
 5. Cancel one order via `cancel_order` or batch via `cancel_all_orders`.
 
+## Unit Safety (P0)
+
+- Monetary fields in major mutation tools support `human:` and `raw:` prefixes.
+- Default behavior is human-readable units (e.g. `1` means `1.0` token), while `raw:<int>` enforces exact raw units.
+- `execute_trade` and `adjust_margin` responses include normalized raw values for auditability.
+
 Minimal query examples:
 
 ```json

package/TOOL_EXAMPLES.md

@@ -80,11 +80,14 @@ It includes:
     "slippagePct": "100",
     "executionFeeToken": "0xQUOTE_TOKEN",
     "leverage": 5,
-    "tradingFee": "raw:100000",
     "marketId": "0xMARKET_ID"
   }
 }
 ```
+Notes:
+- `tradingFee` is optional (auto-computed if omitted).
+- Amount-like fields support `human:` and `raw:` prefixes.
+- `positionId: "0x000...000"` is auto-treated as a new position.
 
 ### `close_position`
 ```json
@@ -234,6 +237,7 @@ Raw precision mode:
   }
 }
 ```
+Success payload includes normalized raw amount under `data.normalized.adjustAmountRaw`.
 
 ### `check_approval`
 ```json

package/dist/prompts/tradingGuide.js

@@ -26,8 +26,10 @@ You are an expert crypto trader using the MYX Protocol. To ensure successful exe
 ## 2. Parameter Tips
 - **Position IDs**: When opening a NEW position, \`positionId\` MUST be an empty string \`""\`.
 - **Decimals**: Human-readable units (e.g., "0.1" BTC) are default for \`open_position_simple\`. SDK-native tools often require raw units; use the \`raw:\` prefix if you need forced precision.
+- **Unit Prefixes**: For mutation tools, prefer explicit prefixes: \`human:\` for readable amounts, \`raw:\` for exact on-chain units.
 - **Slippage**: Default is 100 (1%). For volatile meme tokens, consider 200-300 (2-3%).
 - **Fees**: Use \`get_user_trading_fee_rate\` to estimate fees before large trades.
+- **execute_trade**: Has built-in preflight normalization and can auto-compute \`tradingFee\` when omitted.
 - **Balances**: Use \`get_account\` to clearly separate wallet balance vs trading-account balance (pass \`poolId\` for trading-account metrics).
 - **Adjust Margin**: \`adjust_margin.adjustAmount\` supports human amount (e.g. "1"), and also supports exact raw amount via \`raw:\` prefix.
 - **TP/SL Updates**: \`update_order_tp_sl\` accepts boolean-like values for \`useOrderCollateral\` and \`isTpSlOrder\`, but pending LIMIT/STOP orders can still be rejected by protocol rules; after fill, prefer \`set_tp_sl\`.

package/dist/server.js

@@ -103,6 +103,102 @@ function parseFirstText(result) {
     const firstText = result.content.find((item) => item?.type === "text" && typeof item.text === "string");
     return firstText?.text ?? null;
 }
+function unwrapSchema(schema) {
+    let current = schema;
+    for (let i = 0; i < 8; i++) {
+        const type = current?._def?.type;
+        if (!type)
+            break;
+        if (type === "optional" || type === "nullable" || type === "default" || type === "prefault" || type === "catch") {
+            current = current?._def?.innerType;
+            continue;
+        }
+        if (type === "pipe") {
+            current = current?._def?.out;
+            continue;
+        }
+        break;
+    }
+    return current;
+}
+function coerceBooleanString(input) {
+    if (typeof input !== "string")
+        return input;
+    const normalized = input.trim().toLowerCase();
+    if (normalized === "true" || normalized === "1")
+        return true;
+    if (normalized === "false" || normalized === "0")
+        return false;
+    return input;
+}
+function coerceStringToStringArray(input) {
+    if (Array.isArray(input))
+        return input.map((item) => String(item).trim()).filter(Boolean);
+    if (typeof input !== "string")
+        return input;
+    const text = input.trim();
+    if (!text)
+        return input;
+    if (text.startsWith("[") && text.endsWith("]")) {
+        try {
+            const parsed = JSON.parse(text);
+            if (Array.isArray(parsed)) {
+                return parsed.map((item) => String(item).trim()).filter(Boolean);
+            }
+        }
+        catch {
+        }
+    }
+    if (text.includes(",")) {
+        const split = text.split(",").map((item) => item.trim()).filter(Boolean);
+        if (split.length > 0)
+            return split;
+    }
+    return input;
+}
+function coerceBySchema(value, schema) {
+    const unwrapped = unwrapSchema(schema);
+    const type = unwrapped?._def?.type;
+    if (type === "boolean") {
+        return coerceBooleanString(value);
+    }
+    if (type === "array") {
+        const elementType = unwrapSchema(unwrapped?._def?.element)?._def?.type;
+        if (elementType === "string") {
+            return coerceStringToStringArray(value);
+        }
+    }
+    if (type === "union") {
+        const options = Array.isArray(unwrapped?._def?.options) ? unwrapped._def.options : [];
+        for (const option of options) {
+            const optionType = unwrapSchema(option)?._def?.type;
+            if (optionType === "boolean") {
+                const coerced = coerceBooleanString(value);
+                if (typeof coerced === "boolean")
+                    return coerced;
+            }
+            if (optionType === "array") {
+                const coerced = coerceStringToStringArray(value);
+                if (Array.isArray(coerced))
+                    return coerced;
+            }
+        }
+    }
+    return value;
+}
+function normalizeToolArgsBySchema(rawArgs, schema) {
+    const source = rawArgs && typeof rawArgs === "object" ? { ...rawArgs } : {};
+    const normalized = {};
+    for (const key of Object.keys(source)) {
+        normalized[key] = source[key];
+    }
+    for (const [key, fieldSchema] of Object.entries(schema)) {
+        if (!Object.prototype.hasOwnProperty.call(source, key))
+            continue;
+        normalized[key] = coerceBySchema(source[key], fieldSchema);
+    }
+    return normalized;
+}
 function normalizeToolErrorResult(toolName, result) {
     const rawText = parseFirstText(result);
     if (!rawText) {
@@ -208,27 +304,30 @@ function normalizeSdkReadFailure(toolName, result) {
 function zodSchemaToJsonSchema(zodSchema) {
     const toPropSchema = (value) => {
         const def = value?._def;
-        const typeName = def?.typeName;
-        if (typeName === "ZodOptional" || typeName === "ZodNullable") {
+        const zodType = def?.type;
+        if (zodType === "optional" || zodType === "nullable" || zodType === "default" || zodType === "prefault" || zodType === "catch") {
             return toPropSchema(def?.innerType);
         }
-        if (typeName === "ZodString")
+        if (zodType === "pipe") {
+            return toPropSchema(def?.out);
+        }
+        if (zodType === "string")
             return { type: "string" };
-        if (typeName === "ZodNumber")
+        if (zodType === "number")
             return { type: "number" };
-        if (typeName === "ZodBoolean")
+        if (zodType === "boolean")
             return { type: "boolean" };
-        if (typeName === "ZodArray") {
-            return { type: "array", items: toPropSchema(def?.type) };
+        if (zodType === "array") {
+            return { type: "array", items: toPropSchema(def?.element) };
         }
-        if (typeName === "ZodLiteral") {
+        if (zodType === "literal") {
             return { const: def?.value };
         }
-        if (typeName === "ZodUnion") {
+        if (zodType === "union") {
             const options = def?.options || [];
             return { anyOf: options.map((opt) => toPropSchema(opt)) };
         }
-        if (typeName === "ZodObject") {
+        if (zodType === "object") {
             return { type: "object" };
         }
         return { type: "string" };
@@ -237,7 +336,8 @@ function zodSchemaToJsonSchema(zodSchema) {
     const required = [];
     for (const [key, value] of Object.entries(zodSchema)) {
         const desc = value?._def?.description || "";
-        const isOptional = value?.isOptional?.() || value?._def?.typeName === "ZodOptional";
+        const fieldType = value?._def?.type;
+        const isOptional = value?.isOptional?.() || fieldType === "optional" || fieldType === "default";
         const prop = toPropSchema(value);
         if (desc)
             prop.description = desc;
@@ -252,7 +352,7 @@ function zodSchemaToJsonSchema(zodSchema) {
     };
 }
 // ─── MCP Server ───
-const server = new Server({ name: "myx-mcp-trading-server", version: "3.0.1" }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
+const server = new Server({ name: "myx-mcp-trading-server", version: "3.0.2" }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
 // List tools
 server.setRequestHandler(ListToolsRequestSchema, async () => {
     return {
@@ -279,8 +379,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     try {
         let validatedArgs = args ?? {};
         if (tool.schema) {
+            const normalizedArgs = normalizeToolArgsBySchema(args ?? {}, tool.schema);
             try {
-                validatedArgs = z.object(tool.schema).strict().parse(args ?? {});
+                validatedArgs = z.object(tool.schema).strict().parse(normalizedArgs);
             }
             catch (validationError) {
                 if (validationError instanceof ZodError) {
@@ -372,7 +473,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.1 running (stdio, pure on-chain, prod ready)");
+    logger.info("🚀 MYX Trading MCP Server v3.0.2 running (stdio, pure on-chain, prod ready)");
 }
 main().catch((err) => {
     logger.error("Fatal Server Startup Error", err);

package/dist/services/tradeService.js

@@ -136,7 +136,7 @@ export async function openPosition(client, address, args) {
     }
     const baseDecimals = poolData.baseDecimals || 18;
     const quoteDecimals = poolData.quoteDecimals || 6;
-    const collateralRaw = ensureUnits(args.collateralAmount, quoteDecimals, "collateralAmount");
+    const collateralRaw = ensureUnits(args.collateralAmount, quoteDecimals, "collateralAmount", { allowImplicitRaw: false });
     // --- Pre-flight Check: minOrderSizeInUsd ---
     try {
         const levelRes = await client.markets.getPoolLevelConfig(args.poolId, chainId);
@@ -163,9 +163,9 @@ export async function openPosition(client, address, args) {
             throw e;
         console.warn(`[tradeService] Limit check skipped: ${e.message}`);
     }
-    const sizeRaw = ensureUnits(args.size, baseDecimals, "size");
-    const priceRaw = ensureUnits(args.price, 30, "price");
-    const tradingFeeRaw = ensureUnits(args.tradingFee, quoteDecimals, "tradingFee");
+    const sizeRaw = ensureUnits(args.size, baseDecimals, "size", { allowImplicitRaw: false });
+    const priceRaw = ensureUnits(args.price, 30, "price", { allowImplicitRaw: false });
+    const tradingFeeRaw = ensureUnits(args.tradingFee, quoteDecimals, "tradingFee", { allowImplicitRaw: false });
     // --- Auto-Deposit Logic (Strict) ---
     const allowAutoDeposit = args.autoDeposit !== false;
     console.log(`[tradeService] Checking marginBalance for ${address} in pool ${args.poolId}...`);
@@ -227,13 +227,13 @@ export async function openPosition(client, address, args) {
         leverage: args.leverage,
     };
     if (args.tpSize)
-        orderParams.tpSize = ensureUnits(args.tpSize, baseDecimals, "tpSize");
+        orderParams.tpSize = ensureUnits(args.tpSize, baseDecimals, "tpSize", { allowImplicitRaw: false });
     if (args.tpPrice)
-        orderParams.tpPrice = ensureUnits(args.tpPrice, 30, "tpPrice");
+        orderParams.tpPrice = ensureUnits(args.tpPrice, 30, "tpPrice", { allowImplicitRaw: false });
     if (args.slSize)
-        orderParams.slSize = ensureUnits(args.slSize, baseDecimals, "slSize");
+        orderParams.slSize = ensureUnits(args.slSize, baseDecimals, "slSize", { allowImplicitRaw: false });
     if (args.slPrice)
-        orderParams.slPrice = ensureUnits(args.slPrice, 30, "slPrice");
+        orderParams.slPrice = ensureUnits(args.slPrice, 30, "slPrice", { allowImplicitRaw: false });
     return client.order.createIncreaseOrder(orderParams, tradingFeeRaw, args.marketId);
 }
 /**
@@ -263,9 +263,9 @@ export async function closePosition(client, address, args) {
         orderType: args.orderType,
         triggerType: resolveTriggerType(args.orderType, args.direction, true, args.triggerType),
         direction: dir,
-        collateralAmount: ensureUnits(args.collateralAmount, quoteDecimals, "collateralAmount"),
-        size: ensureUnits(args.size, baseDecimals, "size"),
-        price: ensureUnits(args.price, 30, "price"),
+        collateralAmount: ensureUnits(args.collateralAmount, quoteDecimals, "collateralAmount", { allowImplicitRaw: false }),
+        size: ensureUnits(args.size, baseDecimals, "size", { allowImplicitRaw: false }),
+        price: ensureUnits(args.price, 30, "price", { allowImplicitRaw: false }),
         timeInForce: args.timeInForce,
         postOnly: args.postOnly,
         slippagePct: normalizeSlippagePct4dp(args.slippagePct),
@@ -303,13 +303,13 @@ export async function setPositionTpSl(client, address, args) {
         slippagePct: normalizeSlippagePct4dp(args.slippagePct),
     };
     if (args.tpPrice)
-        params.tpPrice = ensureUnits(args.tpPrice, 30, "tpPrice");
+        params.tpPrice = ensureUnits(args.tpPrice, 30, "tpPrice", { allowImplicitRaw: false });
     if (args.tpSize)
-        params.tpSize = ensureUnits(args.tpSize, baseDecimals, "tpSize");
+        params.tpSize = ensureUnits(args.tpSize, baseDecimals, "tpSize", { allowImplicitRaw: false });
     if (args.slPrice)
-        params.slPrice = ensureUnits(args.slPrice, 30, "slPrice");
+        params.slPrice = ensureUnits(args.slPrice, 30, "slPrice", { allowImplicitRaw: false });
     if (args.slSize)
-        params.slSize = ensureUnits(args.slSize, baseDecimals, "slSize");
+        params.slSize = ensureUnits(args.slSize, baseDecimals, "slSize", { allowImplicitRaw: false });
     return client.order.createPositionTpSlOrder(params);
 }
 /**
@@ -334,7 +334,7 @@ export async function adjustMargin(client, address, args) {
     catch {
         // Fallback to env quote decimals if market detail is unavailable.
     }
-    const adjustAmount = ensureUnits(adjustAmountInput, quoteDecimals, "adjustAmount");
+    const adjustAmount = ensureUnits(adjustAmountInput, quoteDecimals, "adjustAmount", { allowImplicitRaw: false });
     if (!/^-?\d+$/.test(adjustAmount)) {
         throw new Error("adjustAmount must resolve to an integer string (raw units).");
     }
@@ -349,7 +349,14 @@ export async function adjustMargin(client, address, args) {
     if (args.poolOracleType !== undefined) {
         params.poolOracleType = Number(args.poolOracleType);
     }
-    return client.position.adjustCollateral(params);
+    const result = await client.position.adjustCollateral(params);
+    if (result && typeof result === "object") {
+        result.__normalized = {
+            adjustAmountRaw: adjustAmount,
+            quoteToken,
+        };
+    }
+    return result;
 }
 /**
  * 平掉所有仓位
@@ -409,14 +416,14 @@ export async function updateOrderTpSl(client, address, args) {
     const { baseDecimals } = await resolveDecimalsForUpdateOrder(client, chainId, marketId, args.poolId);
     const params = {
         orderId: args.orderId,
-        tpSize: ensureUnits(args.tpSize, baseDecimals, "tpSize"),
-        tpPrice: ensureUnits(args.tpPrice, 30, "tpPrice"),
-        slSize: ensureUnits(args.slSize, baseDecimals, "slSize"),
-        slPrice: ensureUnits(args.slPrice, 30, "slPrice"),
+        tpSize: ensureUnits(args.tpSize, baseDecimals, "tpSize", { allowImplicitRaw: false }),
+        tpPrice: ensureUnits(args.tpPrice, 30, "tpPrice", { allowImplicitRaw: false }),
+        slSize: ensureUnits(args.slSize, baseDecimals, "slSize", { allowImplicitRaw: false }),
+        slPrice: ensureUnits(args.slPrice, 30, "slPrice", { allowImplicitRaw: false }),
         useOrderCollateral: Boolean(args.useOrderCollateral),
         executionFeeToken: quoteToken,
-        size: ensureUnits(args.size, baseDecimals, "size"),
-        price: ensureUnits(args.price, 30, "price"),
+        size: ensureUnits(args.size, baseDecimals, "size", { allowImplicitRaw: false }),
+        price: ensureUnits(args.price, 30, "price", { allowImplicitRaw: false }),
     };
     try {
         const result = await client.order.updateOrderTpSl(params, quoteToken, chainId, address, marketId, isTpSlOrder);

package/dist/tools/accountTransfer.js

@@ -18,7 +18,7 @@ export const accountDepositTool = {
             // ensureUnits handles 'raw:' prefix if absolute precision is needed.
             const { ensureUnits } = await import("../utils/units.js");
             const { getQuoteDecimals } = await import("../auth/resolveClient.js");
-            const amount = ensureUnits(args.amount, getQuoteDecimals(), "amount");
+            const amount = ensureUnits(args.amount, getQuoteDecimals(), "amount", { allowImplicitRaw: false });
             const raw = await client.account.deposit({
                 amount,
                 tokenAddress,
@@ -48,7 +48,7 @@ export const accountWithdrawTool = {
             const { getQuoteDecimals } = await import("../auth/resolveClient.js");
             // Assuming 18 decimals for base and quoteDecimals for quote
             const decimals = args.isQuoteToken ? getQuoteDecimals() : 18;
-            const amount = ensureUnits(args.amount, decimals, "amount");
+            const amount = ensureUnits(args.amount, decimals, "amount", { allowImplicitRaw: false });
             const raw = await client.account.withdraw({
                 chainId,
                 receiver: address,

package/dist/tools/adjustMargin.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { resolveClient } from "../auth/resolveClient.js";
 import { adjustMargin as adjustMarginSvc } from "../services/tradeService.js";
 import { finalizeMutationResult } from "../utils/mutationResult.js";
+import { extractErrorMessage } from "../utils/errorMessage.js";
 export const adjustMarginTool = {
     name: "adjust_margin",
     description: "Adjust the margin (collateral) of an open position.",
@@ -16,11 +17,16 @@ export const adjustMarginTool = {
         try {
             const { client, address, signer } = await resolveClient();
             const raw = await adjustMarginSvc(client, address, args);
+            const normalized = raw?.__normalized;
+            if (raw && typeof raw === "object" && "__normalized" in raw) {
+                delete raw.__normalized;
+            }
             const data = await finalizeMutationResult(raw, signer, "adjust_margin");
-            return { content: [{ type: "text", text: JSON.stringify({ status: "success", data }, (_, v) => typeof v === 'bigint' ? v.toString() : v, 2) }] };
+            const payload = normalized ? { ...data, normalized } : data;
+            return { content: [{ type: "text", text: JSON.stringify({ status: "success", data: payload }, (_, v) => typeof v === 'bigint' ? v.toString() : v, 2) }] };
         }
         catch (error) {
-            return { content: [{ type: "text", text: `Error: ${error.message}` }], isError: true };
+            return { content: [{ type: "text", text: `Error: ${extractErrorMessage(error)}` }], isError: true };
         }
     },
 };

package/dist/tools/executeTrade.js

@@ -1,11 +1,14 @@
 import { z } from "zod";
-import { resolveClient } from "../auth/resolveClient.js";
+import { resolveClient, getChainId } from "../auth/resolveClient.js";
 import { openPosition } from "../services/tradeService.js";
 import { finalizeMutationResult } from "../utils/mutationResult.js";
-import { SLIPPAGE_PCT_4DP_DESC } from "../utils/slippage.js";
+import { normalizeSlippagePct4dp, SLIPPAGE_PCT_4DP_DESC } from "../utils/slippage.js";
 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";
 const POSITION_ID_RE = /^$|^0x[0-9a-fA-F]{64}$/;
+const ZERO_POSITION_ID_RE = /^0x0{64}$/i;
 export const executeTradeTool = {
     name: "execute_trade",
     description: "Create an increase order using SDK-native parameters.",
@@ -13,7 +16,7 @@ export const executeTradeTool = {
         poolId: z.string().describe("Hex Pool ID, e.g. '0x14a19...'. Get via get_pool_list."),
         positionId: z.string().refine((value) => POSITION_ID_RE.test(value), {
             message: "positionId must be empty string for new position, or a bytes32 hex string.",
-        }).describe("Position ID: Use empty string '' for NEW positions, or valid hex for INCREASING existing ones."),
+        }).describe("Position ID: Use empty string '' for NEW positions, or valid hex for INCREASING existing ones. 0x000..00 is auto-treated as NEW."),
         orderType: z.union([z.number(), z.string()]).describe("Market/Limit/Stop. e.g. 0 or 'MARKET'."),
         triggerType: z.union([z.number(), z.string()]).optional().describe("0=None (Market), 1=GTE, 2=LTE. e.g. 'GTE'."),
         direction: z.union([z.number(), z.string()]).describe("0/LONG/BUY or 1/SHORT/SELL."),
@@ -24,33 +27,105 @@ export const executeTradeTool = {
         postOnly: z.coerce.boolean().describe("If true, order only executes as Maker."),
         slippagePct: z.coerce.string().default("50").describe(`${SLIPPAGE_PCT_4DP_DESC}. Default is 50 (0.5%).`),
         executionFeeToken: z.string().describe("Address of token to pay gas/execution fees (typically USDC)."),
-        leverage: z.coerce.number().describe("Leverage multiplier, e.g., 10 for 10x."),
+        leverage: z.coerce.number().positive().describe("Leverage multiplier, e.g., 10 for 10x."),
         tpSize: z.union([z.string(), z.number()]).optional().describe("Take Profit size. Use '0' to disable."),
         tpPrice: z.union([z.string(), z.number()]).optional().describe("Take Profit trigger price."),
         slSize: z.union([z.string(), z.number()]).optional().describe("Stop Loss size. Use '0' to disable."),
         slPrice: z.union([z.string(), z.number()]).optional().describe("Stop Loss trigger price."),
-        tradingFee: z.union([z.string(), z.number()]).describe("Estimated fee in raw units. Fetch via get_user_trading_fee_rate."),
+        tradingFee: z.union([z.string(), z.number()]).optional().describe("Trading fee in quote token units. Supports human/raw prefix. Optional: auto-computed via get_user_trading_fee_rate."),
+        assetClass: z.coerce.number().int().nonnegative().optional().describe("Optional fee lookup assetClass (default from pool config or 1)."),
+        riskTier: z.coerce.number().int().nonnegative().optional().describe("Optional fee lookup riskTier (default from pool config or 1)."),
         marketId: z.string().describe("Specific Market Config Hash. Fetch via get_market_list."),
     },
     handler: async (args) => {
         try {
             const { client, address, signer } = await resolveClient();
+            const chainId = getChainId();
+            const normalizedPositionId = args.positionId === "0" || !args.positionId || ZERO_POSITION_ID_RE.test(String(args.positionId))
+                ? ""
+                : String(args.positionId);
             const poolId = args.poolId;
             // Fetch pool detail to get quoteToken for execution fee
-            const poolResponse = await client.markets.getMarketDetail({ chainId: await resolveClient().then(r => r.chainId), poolId });
+            const poolResponse = await client.markets.getMarketDetail({ chainId, poolId });
             const poolData = poolResponse?.data || (poolResponse?.marketId ? poolResponse : null);
             if (!poolData)
                 throw new Error(`Could not find pool metadata for ID: ${poolId}`);
+            const baseDecimals = Number(poolData.baseDecimals ?? 18);
+            const quoteDecimals = Number(poolData.quoteDecimals ?? 6);
+            const mappedDirection = mapDirection(args.direction);
+            const mappedOrderType = mapOrderType(args.orderType);
+            const mappedTriggerType = args.triggerType !== undefined ? mapTriggerType(args.triggerType) : undefined;
+            const slippagePctNormalized = normalizeSlippagePct4dp(args.slippagePct);
+            const collateralRaw = parseUserUnits(args.collateralAmount, quoteDecimals, "collateralAmount");
+            const sizeRaw = parseUserUnits(args.size, baseDecimals, "size");
+            const priceRaw = parseUserUnits(args.price, 30, "price");
+            if (BigInt(collateralRaw) <= 0n)
+                throw new Error("collateralAmount must be > 0.");
+            if (BigInt(sizeRaw) <= 0n)
+                throw new Error("size must be > 0.");
+            if (BigInt(priceRaw) <= 0n)
+                throw new Error("price must be > 0.");
+            let tradingFeeRaw = "";
+            let tradingFeeMeta = { source: "user" };
+            const tradingFeeInput = String(args.tradingFee ?? "").trim();
+            if (tradingFeeInput) {
+                tradingFeeRaw = parseUserUnits(tradingFeeInput, quoteDecimals, "tradingFee");
+                if (BigInt(tradingFeeRaw) < 0n)
+                    throw new Error("tradingFee must be >= 0.");
+            }
+            else {
+                let poolAssetClass = 1;
+                let poolRiskTier = 1;
+                try {
+                    const levelRes = await client.markets.getPoolLevelConfig(poolId, chainId);
+                    const levelConfig = levelRes?.levelConfig || levelRes?.data?.levelConfig || {};
+                    if (Number.isFinite(Number(levelConfig.assetClass))) {
+                        poolAssetClass = Number(levelConfig.assetClass);
+                    }
+                    if (Number.isFinite(Number(levelConfig.riskTier))) {
+                        poolRiskTier = Number(levelConfig.riskTier);
+                    }
+                }
+                catch {
+                }
+                const assetClass = Number(args.assetClass ?? poolAssetClass ?? 1);
+                const riskTier = Number(args.riskTier ?? poolRiskTier ?? 1);
+                const feeRes = await client.utils.getUserTradingFeeRate(assetClass, riskTier, chainId);
+                if (Number(feeRes?.code) !== 0 || !feeRes?.data) {
+                    throw new Error(`Failed to compute tradingFee automatically (assetClass=${assetClass}, riskTier=${riskTier}). Provide tradingFee manually.`);
+                }
+                const rateRaw = args.postOnly ? feeRes.data.makerFeeRate : feeRes.data.takerFeeRate;
+                const rateBig = BigInt(String(rateRaw ?? "0"));
+                tradingFeeRaw = ((BigInt(collateralRaw) * rateBig) / 1000000n).toString();
+                tradingFeeMeta = { source: "computed", assetClass, riskTier, feeRate: String(rateRaw ?? "0") };
+            }
             const mappedArgs = {
                 ...args,
-                direction: mapDirection(args.direction),
-                orderType: mapOrderType(args.orderType),
-                triggerType: args.triggerType !== undefined ? mapTriggerType(args.triggerType) : undefined,
+                direction: mappedDirection,
+                orderType: mappedOrderType,
+                triggerType: mappedTriggerType,
                 // Normalize positionId
-                positionId: (args.positionId === "0" || !args.positionId) ? "" : args.positionId,
+                positionId: normalizedPositionId,
                 // Enforce executionFeeToken as quoteToken
-                executionFeeToken: poolData.quoteToken || args.executionFeeToken
+                executionFeeToken: poolData.quoteToken || args.executionFeeToken,
+                collateralAmount: `raw:${collateralRaw}`,
+                size: `raw:${sizeRaw}`,
+                price: `raw:${priceRaw}`,
+                tradingFee: `raw:${tradingFeeRaw}`,
+                slippagePct: slippagePctNormalized,
             };
+            if (args.tpSize !== undefined) {
+                mappedArgs.tpSize = `raw:${parseUserUnits(args.tpSize, baseDecimals, "tpSize")}`;
+            }
+            if (args.tpPrice !== undefined) {
+                mappedArgs.tpPrice = `raw:${parseUserUnits(args.tpPrice, 30, "tpPrice")}`;
+            }
+            if (args.slSize !== undefined) {
+                mappedArgs.slSize = `raw:${parseUserUnits(args.slSize, baseDecimals, "slSize")}`;
+            }
+            if (args.slPrice !== undefined) {
+                mappedArgs.slPrice = `raw:${parseUserUnits(args.slPrice, 30, "slPrice")}`;
+            }
             const raw = await openPosition(client, address, mappedArgs);
             const data = await finalizeMutationResult(raw, signer, "execute_trade");
             const txHash = data.confirmation?.txHash;
@@ -58,11 +133,27 @@ export const executeTradeTool = {
             if (txHash) {
                 verification = await verifyTradeOutcome(client, address, args.poolId, txHash);
             }
-            const payload = { ...data, verification };
+            const payload = {
+                ...data,
+                verification,
+                preflight: {
+                    normalized: {
+                        collateralAmountRaw: collateralRaw,
+                        sizeRaw,
+                        priceRaw30: priceRaw,
+                        tradingFeeRaw,
+                        tpSizeRaw: mappedArgs.tpSize?.replace(/^raw:/i, "") ?? null,
+                        tpPriceRaw30: mappedArgs.tpPrice?.replace(/^raw:/i, "") ?? null,
+                        slSizeRaw: mappedArgs.slSize?.replace(/^raw:/i, "") ?? null,
+                        slPriceRaw30: mappedArgs.slPrice?.replace(/^raw:/i, "") ?? null,
+                    },
+                    tradingFeeMeta,
+                },
+            };
             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: ${error.message}` }], isError: true };
+            return { content: [{ type: "text", text: `Error: ${extractErrorMessage(error)}` }], isError: true };
         }
     },
 };

package/dist/utils/units.js

@@ -1,6 +1,7 @@
 import { parseUnits } from "ethers";
 const DECIMAL_RE = /^-?\d+(\.\d+)?$/;
 const RAW_PREFIX_RE = /^raw:/i;
+const HUMAN_PREFIX_RE = /^human:/i;
 const INTEGER_RE = /^-?\d+$/;
 function normalizeDecimal(input) {
     let value = input.trim();
@@ -19,10 +20,14 @@ function normalizeDecimal(input) {
     }
     return `${sign}${intPart || "0"}.${fracPart}`;
 }
-export function ensureUnits(value, decimals, label = "value") {
+export function ensureUnits(value, decimals, label = "value", options = {}) {
+    const allowImplicitRaw = options.allowImplicitRaw ?? true;
     let str = String(value).trim();
     if (!str)
         throw new Error(`${label} is required.`);
+    if (HUMAN_PREFIX_RE.test(str)) {
+        str = str.replace(HUMAN_PREFIX_RE, "").trim();
+    }
     if (RAW_PREFIX_RE.test(str)) {
         const raw = str.replace(RAW_PREFIX_RE, "").trim();
         if (!INTEGER_RE.test(raw))
@@ -39,9 +44,8 @@ export function ensureUnits(value, decimals, label = "value") {
             str = `${parts[0]}.${parts[1].slice(0, decimals)}`;
         }
     }
-    // If it's already a very large integer (e.g. > 12 digits or > decimals digits), 
-    // assume it's already in the smallest unit (Wei/Raw).
-    if (!str.includes(".") && (str.length > 12 || str.length > decimals)) {
+    // Legacy compatibility: optionally treat very large integers as already raw.
+    if (allowImplicitRaw && !str.includes(".") && (str.length > 12 || str.length > decimals)) {
         return str;
     }
     try {
@@ -53,9 +57,12 @@ export function ensureUnits(value, decimals, label = "value") {
     }
 }
 export function parseUserUnits(value, decimals, label = "value") {
-    const str = String(value).trim();
+    let str = String(value).trim();
     if (!str)
         throw new Error(`${label} is required.`);
+    if (HUMAN_PREFIX_RE.test(str)) {
+        str = str.replace(HUMAN_PREFIX_RE, "").trim();
+    }
     if (RAW_PREFIX_RE.test(str)) {
         const raw = str.replace(RAW_PREFIX_RE, "").trim();
         if (!INTEGER_RE.test(raw))

package/package.json

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