@michaleffffff/mcp-trading-server 2.9.2 → 3.0.0

package/dist/prompts/tradingGuide.js

@@ -12,24 +12,27 @@ export const tradingGuidePrompt = {
                     content: {
                         type: "text",
                         text: `
-# MYX Trading MCP Best Practices (v2.8.0)
+# MYX Trading MCP Best Practices (v3.0.0)
 
 You are an expert crypto trader using the MYX Protocol. To ensure successful execution and safe handling of user funds, follow these patterns:
 
 ## 1. The Standard Workflow
-1. **Discovery**: Use \`search_market\` with a keyword (e.g., "BTC") to find the active \`poolId\`.
-2. **Context**: Use \`get_market_price\` and \`get_account_info\` to check the current market state and your available margin.
+1. **Discovery**: Use \`search_market\` with a keyword (or empty keyword) to find active \`poolId\` values. If needed, fallback to \`get_market_list\`.
+2. **Context**: Use \`get_market_price\` and \`get_account\` (with \`poolId\`) to check market state, wallet balance, and trading-account margin.
 3. **Execution**: Prefer \`open_position_simple\` for new trades. It handles unit conversions and pool resolution automatically.
 4. **Validation**: Always check the \`verification.verified\` flag in the output. If \`false\`, read the \`cancelReason\` to explain the failure to the user.
+5. **Limit Order Loop**: For limit orders, always follow \`execute_trade -> get_open_orders -> get_order_history -> cancel_order/cancel_all_orders\`.
 
 ## 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.
 - **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.
+- **Balances**: Use \`get_account\` to clearly separate wallet balance vs trading-account balance (pass \`poolId\` for trading-account metrics).
+- **Examples**: Follow \`TOOL_EXAMPLES.md\` payload patterns when building tool arguments.
 
 ## 3. Self-Healing
-If a transaction reverts with a hex code, the server will attempt to decode it (e.g., "AccountInsufficientFreeAmount"). Inform the user specifically about what is missing rather than giving a generic error.
+If a transaction reverts with a hex code, the server will attempt to decode it (e.g., "AccountInsufficientFreeAmount"). Error payloads now include structured \`code/hint/action\` fields; use them to provide concrete next steps.
 
 Current Session:
 - Wallet: ${address}

package/dist/server.js

@@ -4,7 +4,7 @@ import "dotenv/config";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { z } from "zod";
+import { ZodError, z } from "zod";
 // Tools & Modules
 import * as baseTools from "./tools/index.js";
 import * as baseResources from "./resources/index.js";
@@ -33,6 +33,186 @@ process.on('SIGTERM', shutdown);
 const allTools = Object.values(baseTools);
 const allResources = Object.values(baseResources);
 const allPrompts = Object.values(basePrompts);
+function safeJsonStringify(value) {
+    return JSON.stringify(value, (_, item) => (typeof item === "bigint" ? item.toString() : item), 2);
+}
+function extractErrorMessage(raw) {
+    if (raw instanceof Error)
+        return raw.message;
+    if (typeof raw === "string")
+        return raw;
+    if (raw && typeof raw === "object" && "message" in raw && typeof raw.message === "string") {
+        return String(raw.message);
+    }
+    return String(raw ?? "Unknown error");
+}
+function inferToolErrorCode(message) {
+    const lower = message.toLowerCase();
+    if (lower.includes("required") || lower.includes("invalid") || lower.includes("must be") || lower.includes("unexpected") || lower.includes("unrecognized")) {
+        return "INVALID_PARAM";
+    }
+    if (lower.includes("insufficient") && (lower.includes("allowance") || lower.includes("approval"))) {
+        return "INSUFFICIENT_ALLOWANCE";
+    }
+    if (lower.includes("insufficient") || lower.includes("not enough balance") || lower.includes("insufficientbalance")) {
+        return "INSUFFICIENT_BALANCE";
+    }
+    if (lower.includes("not found") || lower.includes("unknown tool")) {
+        return "NOT_FOUND";
+    }
+    if (lower.includes("timeout") || lower.includes("not confirmed")) {
+        return "TIMEOUT";
+    }
+    if (lower.includes("network") || lower.includes("rpc")) {
+        return "NETWORK_ERROR";
+    }
+    return "TOOL_EXECUTION_ERROR";
+}
+function defaultHintForErrorCode(code, toolName) {
+    if (code === "INVALID_PARAM") {
+        return `Check required fields/types for "${toolName}" and retry.`;
+    }
+    if (code === "INSUFFICIENT_ALLOWANCE") {
+        return `Run "check_approval" before retrying "${toolName}".`;
+    }
+    if (code === "INSUFFICIENT_BALANCE") {
+        return "Top up wallet/trading-account balance or reduce order size.";
+    }
+    if (code === "NOT_FOUND") {
+        return "Verify identifiers (poolId/orderId/marketId) and retry.";
+    }
+    if (code === "TIMEOUT") {
+        return "Query order/position status first, then retry only if needed.";
+    }
+    if (code === "NETWORK_ERROR") {
+        return "Check RPC/network health and retry.";
+    }
+    return `Check prerequisites for "${toolName}" and retry.`;
+}
+function errorResult(payload) {
+    const body = {
+        status: "error",
+        error: {
+            tool: payload.tool,
+            code: payload.code,
+            message: payload.message,
+            hint: payload.hint,
+            action: payload.action,
+            details: payload.details,
+        },
+    };
+    return {
+        content: [{ type: "text", text: safeJsonStringify(body) }],
+        isError: true,
+    };
+}
+function parseFirstText(result) {
+    if (!result || !Array.isArray(result.content))
+        return null;
+    const firstText = result.content.find((item) => item?.type === "text" && typeof item.text === "string");
+    return firstText?.text ?? null;
+}
+function normalizeToolErrorResult(toolName, result) {
+    const rawText = parseFirstText(result);
+    if (!rawText) {
+        return errorResult({
+            tool: toolName,
+            code: "TOOL_EXECUTION_ERROR",
+            message: `Tool "${toolName}" returned an empty error.`,
+            hint: defaultHintForErrorCode("TOOL_EXECUTION_ERROR", toolName),
+            action: "Inspect server logs for details.",
+        });
+    }
+    let parsed = null;
+    try {
+        parsed = JSON.parse(rawText);
+    }
+    catch {
+        parsed = null;
+    }
+    if (parsed &&
+        parsed.status === "error" &&
+        parsed.error &&
+        typeof parsed.error.code === "string" &&
+        typeof parsed.error.message === "string") {
+        return result;
+    }
+    const plainMessage = typeof parsed?.error?.message === "string"
+        ? parsed.error.message
+        : typeof parsed?.message === "string"
+            ? parsed.message
+            : rawText.replace(/^Error:\s*/i, "").trim();
+    const code = typeof parsed?.error?.code === "string"
+        ? parsed.error.code
+        : inferToolErrorCode(plainMessage);
+    return errorResult({
+        tool: toolName,
+        code,
+        message: plainMessage,
+        hint: defaultHintForErrorCode(code, toolName),
+        action: "Adjust parameters/prerequisites and retry.",
+    });
+}
+function validationErrorResult(toolName, error) {
+    const issues = error.issues.map((issue) => {
+        const pathValue = issue.path.length > 0 ? issue.path.map(String).join(".") : "input";
+        return {
+            field: pathValue,
+            code: issue.code,
+            message: issue.message,
+        };
+    });
+    const firstIssue = issues[0];
+    const firstHint = firstIssue
+        ? `Fix "${firstIssue.field}": ${firstIssue.message}`
+        : `Check input schema for "${toolName}".`;
+    return errorResult({
+        tool: toolName,
+        code: "INVALID_PARAM",
+        message: `Invalid arguments for tool "${toolName}".`,
+        hint: firstHint,
+        action: "Call list_tools and resend valid arguments.",
+        details: { issues },
+    });
+}
+function normalizeSdkReadFailure(toolName, result) {
+    const rawText = parseFirstText(result);
+    if (!rawText)
+        return result;
+    let parsed = null;
+    try {
+        parsed = JSON.parse(rawText);
+    }
+    catch {
+        return result;
+    }
+    if (!parsed || parsed.status !== "success")
+        return result;
+    const data = parsed.data;
+    const hasCode = !!data && typeof data === "object" && !Array.isArray(data) && Object.prototype.hasOwnProperty.call(data, "code");
+    if (!hasCode)
+        return result;
+    const code = Number(data.code);
+    if (!Number.isFinite(code) || code === 0)
+        return result;
+    const sdkPayload = data.data;
+    const hasPayload = sdkPayload !== null &&
+        sdkPayload !== undefined &&
+        (!Array.isArray(sdkPayload) || sdkPayload.length > 0);
+    if (code > 0 && hasPayload) {
+        // Some SDK APIs return non-zero positive codes with usable payloads.
+        return result;
+    }
+    const sdkMessage = String(data.msg ?? data.message ?? `SDK read failed with code=${code}.`);
+    return errorResult({
+        tool: toolName,
+        code: "SDK_READ_ERROR",
+        message: `${toolName} failed: code=${code}, msg=${sdkMessage}`,
+        hint: "Check chain/account context and required params, then retry.",
+        action: "Retry or call prerequisite tools to refresh context.",
+        details: { sdk: data },
+    });
+}
 // 将 Zod schema 转换为 JSON Schema (tool listing 用)
 function zodSchemaToJsonSchema(zodSchema) {
     const toPropSchema = (value) => {
@@ -81,7 +261,7 @@ function zodSchemaToJsonSchema(zodSchema) {
     };
 }
 // ─── MCP Server ───
-const server = new Server({ name: "myx-mcp-trading-server", version: "2.9.2" }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
+const server = new Server({ name: "myx-mcp-trading-server", version: "3.0.0" }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
 // List tools
 server.setRequestHandler(ListToolsRequestSchema, async () => {
     return {
@@ -97,30 +277,50 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     const tool = allTools.find((t) => t.name === name);
     if (!tool) {
-        return {
-            content: [{ type: "text", text: `Error: Unknown tool "${name}"` }],
-            isError: true,
-        };
+        return errorResult({
+            tool: name,
+            code: "NOT_FOUND",
+            message: `Unknown tool "${name}".`,
+            hint: "Use list_tools to discover available tool names.",
+            action: "Retry with a valid tool name.",
+        });
     }
     try {
         let validatedArgs = args ?? {};
         if (tool.schema) {
-            validatedArgs = z.object(tool.schema).strict().parse(args ?? {});
+            try {
+                validatedArgs = z.object(tool.schema).strict().parse(args ?? {});
+            }
+            catch (validationError) {
+                if (validationError instanceof ZodError) {
+                    return validationErrorResult(name, validationError);
+                }
+                throw validationError;
+            }
         }
         logger.toolExecution(name, validatedArgs);
         const result = await tool.handler(validatedArgs);
-        if (result && result.content)
-            return result;
+        if (result?.isError) {
+            return normalizeToolErrorResult(name, result);
+        }
+        if (result && result.content) {
+            return normalizeSdkReadFailure(name, result);
+        }
         return {
-            content: [{ type: "text", text: JSON.stringify({ status: "success", data: result }, (_, v) => typeof v === 'bigint' ? v.toString() : v, 2) }],
+            content: [{ type: "text", text: safeJsonStringify({ status: "success", data: result }) }],
         };
     }
     catch (error) {
         logger.error(`Error executing tool: ${name}`, error);
-        return {
-            content: [{ type: "text", text: `Error: ${error.message}` }],
-            isError: true,
-        };
+        const message = extractErrorMessage(error);
+        const code = inferToolErrorCode(message);
+        return errorResult({
+            tool: name,
+            code,
+            message,
+            hint: defaultHintForErrorCode(code, name),
+            action: "Fix inputs/prerequisites and retry.",
+        });
     }
 });
 // Resources Handlers
@@ -181,7 +381,7 @@ server.setRequestHandler(GetPromptRequestSchema, async (request) => {
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    logger.info("🚀 MYX Trading MCP Server v2.9.2 running (stdio, pure on-chain, prod ready)");
+    logger.info("🚀 MYX Trading MCP Server v3.0.0 running (stdio, pure on-chain, prod ready)");
 }
 main().catch((err) => {
     logger.error("Fatal Server Startup Error", err);

package/dist/services/marketService.js

@@ -1,5 +1,65 @@
 import { getChainId } from "../auth/resolveClient.js";
 import { getMarketStateDesc } from "../utils/mappings.js";
+function collectRows(input) {
+    if (Array.isArray(input))
+        return input.flatMap(collectRows);
+    if (!input || typeof input !== "object")
+        return [];
+    if (input.poolId || input.pool_id)
+        return [input];
+    return Object.values(input).flatMap(collectRows);
+}
+function extractMarketRows(raw, chainId) {
+    if (raw?.contractInfo && Array.isArray(raw.contractInfo.list)) {
+        return raw.contractInfo.list;
+    }
+    if (Array.isArray(raw?.data)) {
+        return raw.data;
+    }
+    if (raw?.data && Array.isArray(raw.data[chainId])) {
+        return raw.data[chainId];
+    }
+    if (Array.isArray(raw)) {
+        return raw;
+    }
+    return collectRows(raw?.data ?? raw);
+}
+function normalizeMarketState(value) {
+    if (value === undefined || value === null || value === "")
+        return null;
+    const casted = Number(value);
+    return Number.isFinite(casted) ? casted : null;
+}
+function normalizePoolId(row) {
+    const poolId = row?.poolId ?? row?.pool_id ?? "";
+    return String(poolId);
+}
+function matchesKeyword(row, keywordUpper) {
+    const poolId = normalizePoolId(row);
+    const haystack = [
+        row?.baseSymbol,
+        row?.quoteSymbol,
+        row?.baseQuoteSymbol,
+        row?.symbolName,
+        row?.name,
+        poolId,
+        row?.baseToken,
+        row?.quoteToken,
+        row?.marketId,
+    ]
+        .map((value) => String(value ?? "").toUpperCase())
+        .join("|");
+    return haystack.includes(keywordUpper);
+}
+async function fetchApiMarketRows(client) {
+    const marketListRes = await client.api.getMarketList().catch(() => null);
+    const marketRows = extractMarketRows(marketListRes, getChainId());
+    const marketRowsWithPoolId = marketRows.filter((row) => normalizePoolId(row));
+    if (marketRowsWithPoolId.length > 0)
+        return marketRowsWithPoolId;
+    const poolListRes = await client.api.getPoolList().catch(() => null);
+    return collectRows(poolListRes?.data ?? poolListRes);
+}
 export async function getMarketPrice(client, poolId, chainIdOverride) {
     const chainId = chainIdOverride ?? getChainId();
     const tickerRes = await client.markets.getTickerList({
@@ -15,28 +75,45 @@ export async function getOraclePrice(client, poolId, chainIdOverride) {
 }
 export async function searchMarket(client, keyword, limit = 1000) {
     const chainId = getChainId();
-    const searchRes = await client.markets.searchMarket({ chainId, keyword, limit });
-    const raw = searchRes;
+    const normalizedKeyword = String(keyword ?? "").trim();
+    const requestedLimit = Number.isFinite(limit) && limit > 0 ? Math.floor(limit) : 1000;
     let dataList = [];
-    if (raw && raw.contractInfo && Array.isArray(raw.contractInfo.list)) {
-        dataList = raw.contractInfo.list;
+    try {
+        const searchRes = await client.markets.searchMarket({ chainId, keyword: normalizedKeyword, limit: requestedLimit });
+        dataList = extractMarketRows(searchRes, chainId);
     }
-    else if (raw && Array.isArray(raw.data)) {
-        dataList = raw.data;
+    catch {
+        dataList = [];
     }
-    else if (raw && raw.data && Array.isArray(raw.data[chainId])) {
-        dataList = raw.data[chainId];
+    if (dataList.length === 0 || normalizedKeyword.length === 0) {
+        const fallbackRows = await fetchApiMarketRows(client);
+        if (fallbackRows.length > 0) {
+            dataList = fallbackRows;
+        }
     }
-    else if (raw && Array.isArray(raw)) {
-        dataList = raw;
+    const filteredRows = normalizedKeyword
+        ? dataList.filter((row) => matchesKeyword(row, normalizedKeyword.toUpperCase()))
+        : dataList;
+    const dedupedByPoolId = new Map();
+    for (const row of filteredRows) {
+        const poolId = normalizePoolId(row);
+        if (!poolId)
+            continue;
+        if (!dedupedByPoolId.has(poolId)) {
+            dedupedByPoolId.set(poolId, row);
+        }
     }
-    // Filter tradable markets (state=2 => Active)
-    const activeMarkets = dataList.filter(m => Number(m.state) === 2);
+    const activeMarkets = Array.from(dedupedByPoolId.values())
+        .filter((row) => {
+        const state = normalizeMarketState(row?.state ?? row?.poolState);
+        return state === null || state === 2;
+    })
+        .slice(0, requestedLimit);
     // Get tickers for these pools to get price and change24h
     let tickers = [];
     if (activeMarkets.length > 0) {
         try {
-            const poolIds = activeMarkets.map(m => m.poolId);
+            const poolIds = activeMarkets.map((market) => normalizePoolId(market));
             const tickerRes = await client.markets.getTickerList({ chainId, poolIds });
             tickers = Array.isArray(tickerRes) ? tickerRes : (tickerRes?.data || []);
         }
@@ -44,17 +121,20 @@ export async function searchMarket(client, keyword, limit = 1000) {
             console.error("Failed to fetch tickers:", e);
         }
     }
-    return activeMarkets.map(m => {
-        const ticker = tickers.find(t => String(t.poolId).toLowerCase() === String(m.poolId).toLowerCase());
+    return activeMarkets.map((market) => {
+        const poolId = normalizePoolId(market);
+        const state = normalizeMarketState(market?.state ?? market?.poolState);
+        const ticker = tickers.find((t) => String(t.poolId).toLowerCase() === poolId.toLowerCase());
+        const symbol = market?.baseQuoteSymbol || [market?.baseSymbol, market?.quoteSymbol].filter(Boolean).join("/");
         return {
-            symbol: m.baseQuoteSymbol || `${m.baseSymbol}/${m.quoteSymbol}`,
-            name: m.symbolName || m.name,
-            poolId: m.poolId,
+            symbol: symbol || market?.symbolName || poolId,
+            name: market?.symbolName || market?.name || symbol || poolId,
+            poolId,
             price: ticker ? ticker.price : "0",
             change24h: ticker ? ticker.change : "0",
-            tvl: m.tvl || "0",
-            state: m.state,
-            stateDescription: getMarketStateDesc(m.state)
+            tvl: market?.tvl || "0",
+            state: state ?? "unknown",
+            stateDescription: state === null ? "Unknown" : getMarketStateDesc(state)
         };
     });
 }
@@ -128,7 +208,13 @@ export async function resolvePool(client, poolId, keyword) {
                 const base = String(row?.baseSymbol ?? "").toUpperCase();
                 const pair = String(row?.baseQuoteSymbol ?? "").toUpperCase();
                 const id = String(row?.poolId ?? row?.pool_id ?? "").toUpperCase();
-                return base === searchKey || pair.includes(searchKey) || id === searchKey;
+                const baseToken = String(row?.baseToken ?? row?.base_token ?? "").toUpperCase();
+                const quoteToken = String(row?.quoteToken ?? row?.quote_token ?? "").toUpperCase();
+                return base === searchKey ||
+                    pair.includes(searchKey) ||
+                    id === searchKey ||
+                    baseToken === searchKey ||
+                    quoteToken === searchKey;
             });
             if (match) {
                 return String(match.poolId ?? match.pool_id);

package/dist/tools/accountInfo.js

@@ -1,40 +1,132 @@
 import { z } from "zod";
 import { resolveClient, getChainId } from "../auth/resolveClient.js";
+import { getBalances, getMarginBalance } from "../services/balanceService.js";
 import { getTradeFlowTypeDesc } from "../utils/mappings.js";
-export const getAccountInfoTool = {
-    name: "get_account_info",
-    description: "Get full account information for a pool (freeMargin, quoteProfit, etc.). Essential for risk management.",
+function readErrorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === "string")
+        return error;
+    if (error && typeof error === "object" && "message" in error) {
+        return String(error.message);
+    }
+    return String(error ?? "unknown error");
+}
+function assertSdkReadSuccess(result, actionName) {
+    if (!result || typeof result !== "object" || Array.isArray(result))
+        return;
+    if (!Object.prototype.hasOwnProperty.call(result, "code"))
+        return;
+    const code = Number(result.code);
+    if (!Number.isFinite(code) || code === 0)
+        return;
+    const payload = result.data;
+    const hasPayload = payload !== null &&
+        payload !== undefined &&
+        (!Array.isArray(payload) || payload.length > 0);
+    if (code > 0 && hasPayload) {
+        // Keep aligned with server-side read normalization:
+        // positive non-zero code with usable payload is warning-like.
+        return;
+    }
+    const message = String(result.msg ?? result.message ?? "unknown error");
+    throw new Error(`${actionName} failed: code=${code}, msg=${message}`);
+}
+function normalizeAccountInfo(result) {
+    if (!(result && result.code === 0 && Array.isArray(result.data))) {
+        return result;
+    }
+    const values = result.data;
+    return {
+        ...result,
+        data: {
+            freeMargin: values[0],
+            walletBalance: values[1],
+            freeBaseAmount: values[2],
+            baseProfit: values[3],
+            quoteProfit: values[4],
+            reservedAmount: values[5],
+            releaseTime: values[6],
+            tradeableMargin: (BigInt(values[0]) + BigInt(values[1]) + (BigInt(values[6]) === 0n ? BigInt(values[4]) : 0n)).toString(),
+            baseProfitStatus: "base token to be unlocked",
+            quoteProfitStatus: BigInt(values[6]) > 0n ? "quote token to be unlocked" : "quote token unlocked/available"
+        }
+    };
+}
+export const getAccountTool = {
+    name: "get_account",
+    description: "Unified account snapshot. Distinguishes wallet balance vs trading-account metrics. Provide poolId for full trading-account details.",
     schema: {
-        poolId: z.string().describe("Pool ID"),
+        poolId: z.string().optional().describe("Optional Pool ID. Required to include trading-account metrics (account info + margin)."),
     },
     handler: async (args) => {
         try {
             const { client, address } = await resolveClient();
             const chainId = getChainId();
-            const result = await client.account.getAccountInfo(chainId, address, args.poolId);
-            // Map the raw array to a structured object for better usability
-            let structuredData = result;
-            if (result && result.code === 0 && Array.isArray(result.data)) {
-                const d = result.data;
-                structuredData = {
-                    ...result,
-                    data: {
-                        freeMargin: d[0],
-                        walletBalance: d[1],
-                        freeBaseAmount: d[2],
-                        baseProfit: d[3],
-                        quoteProfit: d[4],
-                        reservedAmount: d[5],
-                        releaseTime: d[6],
-                        // Business Logic: 
-                        // tradeableMargin = freeMargin + walletBalance + (quoteProfit if releaseTime == 0)
-                        tradeableMargin: (BigInt(d[0]) + BigInt(d[1]) + (BigInt(d[6]) === 0n ? BigInt(d[4]) : 0n)).toString(),
-                        baseProfitStatus: "base token to be unlocked",
-                        quoteProfitStatus: BigInt(d[6]) > 0n ? "quote token to be unlocked" : "quote token unlocked/available"
-                    }
-                };
+            const poolId = args.poolId?.trim();
+            const overview = {
+                meta: {
+                    address,
+                    chainId,
+                    poolId: poolId ?? null,
+                    partial: false,
+                },
+                wallet: {
+                    scope: "wallet_balance",
+                    description: "On-chain wallet quote-token balance (funds not yet deposited into trading account).",
+                    quoteTokenBalance: null,
+                    raw: null,
+                    error: null,
+                },
+                tradingAccount: {
+                    scope: "trading_account_balance",
+                    description: poolId
+                        ? "Trading-account metrics for the selected pool."
+                        : "Provide poolId to include trading-account metrics (account info + margin).",
+                    poolId: poolId ?? null,
+                    accountInfo: null,
+                    marginBalance: null,
+                    error: null,
+                },
+                warnings: [],
+            };
+            try {
+                const walletBalances = await getBalances(client, address);
+                assertSdkReadSuccess(walletBalances, "getWalletQuoteTokenBalance");
+                overview.wallet.quoteTokenBalance = walletBalances?.data ?? walletBalances;
+                overview.wallet.raw = walletBalances;
+            }
+            catch (walletError) {
+                overview.meta.partial = true;
+                overview.wallet.error = readErrorMessage(walletError);
+                overview.warnings.push(`wallet section failed: ${overview.wallet.error}`);
+            }
+            if (poolId) {
+                try {
+                    const [accountInfoRaw, marginBalanceRaw] = await Promise.all([
+                        client.account.getAccountInfo(chainId, address, poolId),
+                        getMarginBalance(client, address, poolId),
+                    ]);
+                    assertSdkReadSuccess(accountInfoRaw, "getAccountInfo");
+                    assertSdkReadSuccess(marginBalanceRaw, "getAvailableMarginBalance");
+                    overview.tradingAccount.accountInfo = normalizeAccountInfo(accountInfoRaw);
+                    overview.tradingAccount.marginBalance = marginBalanceRaw;
+                }
+                catch (tradingError) {
+                    overview.meta.partial = true;
+                    overview.tradingAccount.error = readErrorMessage(tradingError);
+                    overview.warnings.push(`tradingAccount section failed: ${overview.tradingAccount.error}`);
+                }
+            }
+            if (overview.warnings.length === 0) {
+                delete overview.warnings;
+            }
+            const hasWalletData = overview.wallet.quoteTokenBalance !== null;
+            const hasTradingData = overview.tradingAccount.accountInfo !== null || overview.tradingAccount.marginBalance !== null;
+            if (!hasWalletData && !hasTradingData) {
+                throw new Error("Failed to build account snapshot: wallet and trading-account sections both unavailable.");
             }
-            return { content: [{ type: "text", text: JSON.stringify({ status: "success", data: structuredData }, (_, v) => typeof v === 'bigint' ? v.toString() : v, 2) }] };
+            return { content: [{ type: "text", text: JSON.stringify({ status: "success", data: overview }, (_, v) => typeof v === 'bigint' ? v.toString() : v, 2) }] };
         }
         catch (error) {
             return { content: [{ type: "text", text: `Error: ${error.message}` }], isError: true };
@@ -65,25 +157,3 @@ export const getTradeFlowTool = {
         }
     },
 };
-export const getMarginBalanceTool = {
-    name: "get_margin_balance",
-    description: "Get available margin balance for a specific pool.",
-    schema: {
-        poolId: z.string().describe("Pool ID"),
-    },
-    handler: async (args) => {
-        try {
-            const { client, address } = await resolveClient();
-            const chainId = getChainId();
-            const result = await client.account.getAvailableMarginBalance({
-                poolId: args.poolId,
-                chainId,
-                address,
-            });
-            return { content: [{ type: "text", text: JSON.stringify({ status: "success", data: result }, (_, v) => typeof v === 'bigint' ? v.toString() : v, 2) }] };
-        }
-        catch (error) {
-            return { content: [{ type: "text", text: `Error: ${error.message}` }], isError: true };
-        }
-    },
-};