@aihubspot/agent-trade-mcp 0.1.7 → 0.1.9

package/README.md

@@ -23,7 +23,7 @@ Setup registers the currently installed MCP binary through its absolute Node run
 
 Use `spot_prepare_market_buy` or `margin_prepare_market_buy` only with `quoteAmount` (for example, the exact USDT amount to spend for `ETHUSDT`). Use `spot_prepare_market_sell` or `margin_prepare_market_sell` only with `baseQuantity` (the exact ETH amount to sell for `ETHUSDT`). A market buy cannot guarantee an exact base-asset quantity; it must never reinterpret a requested base quantity as a quote amount.
 
-Before any order preview, MCP lazily loads `/sapi/v2/symbols` once per local profile and caches the symbol rules in memory for five minutes. Known quantity/price precision and limit-order minimum violations are rejected before confirmation.
+Before any order preview, MCP lazily loads `/sapi/v2/symbols` once per local profile and caches the symbol rules for one hour in memory and an isolated local cache. Known quantity/price precision and limit-order minimum violations are rejected before confirmation.
 
 ## Read response
 
@@ -39,7 +39,10 @@ MCP clients that support the current protocol also receive the same envelope in
 
 Use these tools for requests that would otherwise return a broad market payload:
 
-- `market_search_symbols`: bounded symbol search and metadata. Use this for every MCP symbol lookup; it returns matching rows in `data.value.items`.
+- `market_get_symbol_overview`: counts by quote asset and a small sample. Use this first for a generic request to list trading pairs.
+- `market_list_symbols`: a paged, optionally quote-asset-filtered list without order-rule metadata.
+- `market_search_symbols`: required-keyword lookup with at most 20 basic matching rows. Do not use it for a generic pair list.
+- `market_get_symbol_info`: exact precision and minimum order rules for one symbol only.
 - `market_get_ticker_summary`: watchlist, gainers, losers, and quote-volume leaders.
 - `market_get_depth_summary`: best bid/ask, spread, and up to 20 levels per side.
 - `market_get_trades_summary`: price range, buy/sell statistics, and up to 50 recent trades.

package/dist/index.js

@@ -656,29 +656,82 @@ function optionalClientOrderId(input) {
 }
 
 // ../core/src/tools/asset-tools.ts
-var accountTypes = ["1", "2", "3", "4", "5"];
+var ACCOUNT_TYPES = ["1", "2", "3", "4", "5"];
+var ACCOUNT_TYPE_NAMES = {
+  "1": "Spot",
+  "2": "Isolated Margin",
+  "3": "Cross Margin",
+  "4": "C2C",
+  "5": "Derivatives"
+};
+var accountTypeSchema = {
+  type: "string",
+  oneOf: [
+    { const: "1", title: "Spot (1)" },
+    { const: "2", title: "Isolated Margin (2; symbol required)" },
+    { const: "3", title: "Cross Margin (3)" },
+    { const: "4", title: "C2C (4)" },
+    { const: "5", title: "Derivatives (5)" }
+  ],
+  description: "Account type: 1=Spot, 2=Isolated Margin (requires symbol), 3=Cross Margin, 4=C2C, 5=Derivatives. Do not use 2 for Derivatives."
+};
+var spotDerivativeAccounts = ["EXCHANGE", "FUTURE"];
 function accountType(value, name) {
   const result2 = requiredString(value, name);
-  if (!accountTypes.includes(result2)) throw new AiHubError("AI_HUB_INVALID_ARGUMENT", `${name} must be an account type from 1 to 5.`);
+  if (!ACCOUNT_TYPES.includes(result2)) throw new AiHubError("AI_HUB_INVALID_ARGUMENT", `${name} must be an account type: 1=Spot, 2=Isolated Margin, 3=Cross Margin, 4=C2C, or 5=Derivatives.`);
   return result2;
 }
+function accountTypeName(value) {
+  return ACCOUNT_TYPE_NAMES[value];
+}
+function isIsolatedMarginTransfer(fromAccountType, toAccountType) {
+  return fromAccountType === "2" || toAccountType === "2";
+}
 function requiredTransfer(input) {
   const value = strictObject(input, ["fromAccountType", "toAccountType", "symbol", "coinSymbol", "amount"]);
-  return { fromAccountType: accountType(value, "fromAccountType"), toAccountType: accountType(value, "toAccountType"), coinSymbol: requiredString(value, "coinSymbol"), amount: positiveDecimal(value, "amount"), ...optionalString(value, "symbol") ? { symbol: optionalString(value, "symbol") } : {} };
+  const fromAccountType = accountType(value, "fromAccountType");
+  const toAccountType = accountType(value, "toAccountType");
+  if (fromAccountType === toAccountType) throw new AiHubError("AI_HUB_INVALID_ARGUMENT", "fromAccountType and toAccountType must be different.");
+  const symbol = optionalString(value, "symbol");
+  if (isIsolatedMarginTransfer(fromAccountType, toAccountType) && !symbol) {
+    throw new AiHubError("AI_HUB_ISOLATED_MARGIN_SYMBOL_REQUIRED", "symbol is required when fromAccountType or toAccountType is 2 (Isolated Margin). Provide the isolated-margin trading pair, for example ETHUSDT.");
+  }
+  return { fromAccountType, toAccountType, coinSymbol: requiredString(value, "coinSymbol"), amount: positiveDecimal(value, "amount"), ...symbol ? { symbol } : {} };
 }
 function transferQuery(input) {
   const value = strictObject(input, ["fromAccountType", "toAccountType", "symbol", "coinSymbol", "page", "pageSize"]);
-  return { fromAccountType: accountType(value, "fromAccountType"), toAccountType: accountType(value, "toAccountType"), page: optionalPositiveInteger(value, "page", 1), pageSize: optionalPositiveInteger(value, "pageSize", 20, 100), ...optionalString(value, "symbol") ? { symbol: optionalString(value, "symbol") } : {}, ...optionalString(value, "coinSymbol") ? { coinSymbol: optionalString(value, "coinSymbol") } : {} };
+  const fromAccountType = accountType(value, "fromAccountType");
+  const toAccountType = accountType(value, "toAccountType");
+  const symbol = optionalString(value, "symbol");
+  if (isIsolatedMarginTransfer(fromAccountType, toAccountType) && !symbol) {
+    throw new AiHubError("AI_HUB_ISOLATED_MARGIN_SYMBOL_REQUIRED", "symbol is required when fromAccountType or toAccountType is 2 (Isolated Margin). Provide the isolated-margin trading pair, for example ETHUSDT.");
+  }
+  return { fromAccountType, toAccountType, page: optionalPositiveInteger(value, "page", 1), pageSize: optionalPositiveInteger(value, "pageSize", 20, 100), ...symbol ? { symbol } : {}, ...optionalString(value, "coinSymbol") ? { coinSymbol: optionalString(value, "coinSymbol") } : {} };
 }
 function transferAccounts(input) {
   const value = strictObject(input, ["coinSymbol", "amount", "fromAccount", "toAccount"]);
-  return { coinSymbol: requiredString(value, "coinSymbol"), amount: positiveDecimal(value, "amount"), fromAccount: requiredString(value, "fromAccount"), toAccount: requiredString(value, "toAccount") };
+  const fromAccount = requiredString(value, "fromAccount").toUpperCase();
+  const toAccount = requiredString(value, "toAccount").toUpperCase();
+  if (!spotDerivativeAccounts.includes(fromAccount) || !spotDerivativeAccounts.includes(toAccount) || fromAccount === toAccount) {
+    throw new AiHubError("AI_HUB_INVALID_ARGUMENT", "account transfer supports only EXCHANGE -> FUTURE or FUTURE -> EXCHANGE. Use wallet transfer for isolated margin, cross margin, or C2C.");
+  }
+  return { coinSymbol: requiredString(value, "coinSymbol"), amount: positiveDecimal(value, "amount"), fromAccount, toAccount };
 }
 function transferAccountHistory(input) {
   const value = strictObject(input, ["transferId", "coinSymbol", "fromAccount", "toAccount", "startTime", "endTime", "page", "limit"]);
   const transferId = optionalString(value, "transferId");
   if (!transferId && (!optionalString(value, "fromAccount") || !optionalString(value, "toAccount"))) throw new AiHubError("AI_HUB_INVALID_ARGUMENT", "fromAccount and toAccount are required when transferId is omitted.");
-  return { ...transferId ? { transferId } : {}, ...optionalString(value, "coinSymbol") ? { coinSymbol: optionalString(value, "coinSymbol") } : {}, ...optionalString(value, "fromAccount") ? { fromAccount: optionalString(value, "fromAccount") } : {}, ...optionalString(value, "toAccount") ? { toAccount: optionalString(value, "toAccount") } : {}, ...optionalString(value, "startTime") ? { startTime: optionalString(value, "startTime") } : {}, ...optionalString(value, "endTime") ? { endTime: optionalString(value, "endTime") } : {}, page: optionalPositiveInteger(value, "page", 1), limit: optionalPositiveInteger(value, "limit", 20, 100) };
+  const fromAccount = optionalString(value, "fromAccount")?.toUpperCase();
+  const toAccount = optionalString(value, "toAccount")?.toUpperCase();
+  if (!transferId && (!spotDerivativeAccounts.includes(fromAccount) || !spotDerivativeAccounts.includes(toAccount) || fromAccount === toAccount)) {
+    throw new AiHubError("AI_HUB_INVALID_ARGUMENT", "account transfer history supports only EXCHANGE -> FUTURE or FUTURE -> EXCHANGE when transferId is omitted.");
+  }
+  return { ...transferId ? { transferId } : {}, ...optionalString(value, "coinSymbol") ? { coinSymbol: optionalString(value, "coinSymbol") } : {}, ...fromAccount ? { fromAccount } : {}, ...toAccount ? { toAccount } : {}, ...optionalString(value, "startTime") ? { startTime: optionalString(value, "startTime") } : {}, ...optionalString(value, "endTime") ? { endTime: optionalString(value, "endTime") } : {}, page: optionalPositiveInteger(value, "page", 1), limit: optionalPositiveInteger(value, "limit", 20, 100) };
+}
+function withAccountTypeMetadata(response, value) {
+  const metadata = { accountType: value, accountTypeName: accountTypeName(value) };
+  if (response && typeof response === "object" && !Array.isArray(response)) return { ...response, ...metadata };
+  return { ...metadata, response };
 }
 function pagedDates(input) {
   const value = strictObject(input, ["startTime", "endTime", "page", "pageSize"]);
@@ -691,18 +744,21 @@ function coinOnly(input) {
 var assetTools = [
   {
     name: "account_transfer",
-    title: "Transfer Between Accounts",
-    description: "Transfer an asset between documented account types after confirmation.",
+    title: "Transfer Between Spot and Derivatives",
+    description: "Transfer only between Spot and Derivatives after confirmation. Use fromAccount=EXCHANGE and toAccount=FUTURE for Spot to Derivatives; use the reverse for Derivatives to Spot. Do not pass numeric account types to this Tool.",
     cliPath: ["account", "transfer"],
     module: "spot-account",
     access: "signed",
     operation: "write",
     riskLevel: "high",
-    inputSchema: { type: "object", properties: { coinSymbol: { type: "string" }, amount: { type: "string" }, fromAccount: { type: "string" }, toAccount: { type: "string" } }, required: ["coinSymbol", "amount", "fromAccount", "toAccount"], additionalProperties: false },
+    inputSchema: { type: "object", properties: { coinSymbol: { type: "string" }, amount: { type: "string" }, fromAccount: { type: "string", enum: spotDerivativeAccounts, description: "EXCHANGE means Spot; FUTURE means Derivatives." }, toAccount: { type: "string", enum: spotDerivativeAccounts, description: "EXCHANGE means Spot; FUTURE means Derivatives." } }, required: ["coinSymbol", "amount", "fromAccount", "toAccount"], additionalProperties: false },
     errorCodes: writeErrors,
     validate: transferAccounts,
     handler: (input, context) => context.api.signedPost("/sapi/v1/asset/transfer", input, signed(context)),
-    writeSummary: (input) => ({ action: "account_transfer", ...input })
+    writeSummary: (input) => {
+      const value = input;
+      return { action: "spot_derivatives_transfer", coinSymbol: value.coinSymbol, amount: value.amount, fromAccount: value.fromAccount, fromAccountName: value.fromAccount === "EXCHANGE" ? "Spot" : "Derivatives", toAccount: value.toAccount, toAccountName: value.toAccount === "EXCHANGE" ? "Spot" : "Derivatives" };
+    }
   },
   {
     name: "account_get_transfer_history",
@@ -721,28 +777,31 @@ var assetTools = [
   {
     name: "wallet_universal_transfer",
     title: "Universal Asset Transfer",
-    description: "Transfer between account types after confirmation.",
+    description: "Transfer between numeric account types after confirmation: 1=Spot, 2=Isolated Margin, 3=Cross Margin, 4=C2C, 5=Derivatives. Account type 2 is not Derivatives and requires symbol. For a straightforward Spot to Derivatives transfer, prefer account_transfer with EXCHANGE -> FUTURE.",
     cliPath: ["wallet", "transfer"],
     module: "spot-deposit-withdraw",
     access: "signed",
     operation: "write",
     riskLevel: "high",
-    inputSchema: { type: "object", properties: { fromAccountType: { type: "string" }, toAccountType: { type: "string" }, symbol: { type: "string" }, coinSymbol: { type: "string" }, amount: { type: "string" } }, required: ["fromAccountType", "toAccountType", "coinSymbol", "amount"], additionalProperties: false },
+    inputSchema: { type: "object", properties: { fromAccountType: accountTypeSchema, toAccountType: accountTypeSchema, symbol: { type: "string", description: "Required isolated-margin trading pair when either account type is 2, for example ETHUSDT. Not a Derivatives identifier." }, coinSymbol: { type: "string" }, amount: { type: "string" } }, required: ["fromAccountType", "toAccountType", "coinSymbol", "amount"], additionalProperties: false },
     errorCodes: writeErrors,
     validate: requiredTransfer,
     handler: (input, context) => context.api.signedPost("/sapi/v1/asset/universal_transfer", input, signed(context)),
-    writeSummary: (input) => ({ action: "universal_transfer", ...input })
+    writeSummary: (input) => {
+      const value = input;
+      return { action: "universal_transfer", fromAccountType: value.fromAccountType, fromAccountTypeName: accountTypeName(String(value.fromAccountType)), toAccountType: value.toAccountType, toAccountTypeName: accountTypeName(String(value.toAccountType)), coinSymbol: value.coinSymbol, amount: value.amount, symbol: value.symbol ?? null };
+    }
   },
   {
     name: "wallet_get_universal_transfer_history",
     title: "Get Universal Transfer History",
-    description: "Query universal asset transfer history.",
+    description: "Query universal transfer history using account types 1=Spot, 2=Isolated Margin, 3=Cross Margin, 4=C2C, and 5=Derivatives.",
     cliPath: ["wallet", "transfer-history"],
     module: "spot-deposit-withdraw",
     access: "signed",
     operation: "read",
     riskLevel: "low",
-    inputSchema: { type: "object", properties: { fromAccountType: { type: "string" }, toAccountType: { type: "string" }, symbol: { type: "string" }, coinSymbol: { type: "string" }, page: { type: "integer" }, pageSize: { type: "integer" } }, required: ["fromAccountType", "toAccountType"], additionalProperties: false },
+    inputSchema: { type: "object", properties: { fromAccountType: accountTypeSchema, toAccountType: accountTypeSchema, symbol: { type: "string", description: "Isolated-margin trading pair when account type 2 is involved." }, coinSymbol: { type: "string" }, page: { type: "integer" }, pageSize: { type: "integer" } }, required: ["fromAccountType", "toAccountType"], additionalProperties: false },
     errorCodes: signedReadErrors,
     validate: transferQuery,
     handler: (input, context) => context.api.signedPost("/sapi/v1/asset/universal_transfer_query", input, signed(context))
@@ -795,19 +854,22 @@ var assetTools = [
   {
     name: "wallet_get_transferable_assets",
     title: "Get Transferable Assets",
-    description: "Query assets transferable from one account type.",
+    description: "Query transferable assets for one account type. The response echoes the selected account type and its name: 1=Spot, 2=Isolated Margin, 3=Cross Margin, 4=C2C, 5=Derivatives.",
     cliPath: ["wallet", "transferable-assets"],
     module: "spot-deposit-withdraw",
     access: "signed",
     operation: "read",
     riskLevel: "low",
-    inputSchema: { type: "object", properties: { accountType: { type: "string" } }, required: ["accountType"], additionalProperties: false },
+    inputSchema: { type: "object", properties: { accountType: accountTypeSchema }, required: ["accountType"], additionalProperties: false },
     errorCodes: signedReadErrors,
     validate: (input) => {
       const value = strictObject(input, ["accountType"]);
       return { accountType: accountType(value, "accountType") };
     },
-    handler: (input, context) => context.api.signedPost("/sapi/v1/asset/account/by_type", input, signed(context))
+    handler: async (input, context) => {
+      const value = input;
+      return withAccountTypeMetadata(await context.api.signedPost("/sapi/v1/asset/account/by_type", value, signed(context)), value.accountType);
+    }
   },
   {
     name: "wallet_get_exchange_account",
@@ -970,47 +1032,112 @@ function summarizeTickers(value, options) {
     topByQuoteVolume: [...rows2].sort(compareByNumericField("amount", "desc")).slice(0, limit).map(tickerItem)
   };
 }
-function summarizeSymbols(value, options) {
+function normalizedSymbol(value) {
+  return value.replaceAll("/", "").trim().toUpperCase();
+}
+function parsedSymbolRows(value) {
   const payload = record(value, "Symbols response must be an object.");
   const rows2 = records(payload.symbols, "Symbols response must contain a symbols array.");
-  const query = options.query?.trim().toUpperCase();
-  const quoteAsset = options.quoteAsset?.trim().toUpperCase();
-  const matches = rows2.filter((item) => {
-    const symbol = text(item.SymbolName) ?? text(item.symbol) ?? "";
-    const quote = text(item.quoteAsset)?.toUpperCase();
-    return (!query || symbol.toUpperCase().includes(query)) && (!quoteAsset || quote === quoteAsset);
-  });
-  const sortedMatches = [...matches].sort((left, right) => {
-    if (!query) return 0;
+  return rows2.map((item) => {
+    const apiSymbol = text(item.symbol);
+    const symbol = text(item.SymbolName) ?? apiSymbol ?? "";
+    return {
+      symbol,
+      apiSymbol,
+      baseAsset: text(item.baseAssetName) ?? text(item.baseAsset),
+      quoteAsset: text(item.quoteAssetName) ?? text(item.quoteAsset),
+      pricePrecision: item.pricePrecision ?? null,
+      quantityPrecision: item.quantityPrecision ?? null,
+      limitVolumeMin: text(item.limitVolumeMin),
+      limitPriceMin: text(item.limitPriceMin),
+      limitAmountMin: text(item.limitAmountMin)
+    };
+  }).filter((item) => Boolean(item.symbol));
+}
+function quoteAssetCounts(rows2) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const item of rows2) {
+    const quote = item.quoteAsset?.toUpperCase();
+    if (quote) counts.set(quote, (counts.get(quote) ?? 0) + 1);
+  }
+  return [...counts.entries()].sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0])).map(([asset, count]) => ({ asset, count }));
+}
+function basicSymbolItem(item) {
+  return {
+    symbol: item.symbol,
+    apiSymbol: item.apiSymbol,
+    baseAsset: item.baseAsset,
+    quoteAsset: item.quoteAsset
+  };
+}
+function fullSymbolItem(item) {
+  return {
+    ...basicSymbolItem(item),
+    pricePrecision: item.pricePrecision,
+    quantityPrecision: item.quantityPrecision,
+    limitVolumeMin: item.limitVolumeMin,
+    limitPriceMin: item.limitPriceMin,
+    limitAmountMin: item.limitAmountMin
+  };
+}
+function sortSymbolMatches(rows2, query) {
+  const normalizedQuery = query?.trim().toUpperCase();
+  return [...rows2].sort((left, right) => {
+    if (!normalizedQuery) return left.symbol.localeCompare(right.symbol);
     const rank = (item) => {
-      const symbol = (text(item.SymbolName) ?? text(item.symbol) ?? "").toUpperCase();
-      return symbol.startsWith(`${query}/`) ? 0 : symbol.startsWith(query) ? 1 : 2;
+      const symbol = item.symbol.toUpperCase();
+      return symbol.startsWith(`${normalizedQuery}/`) ? 0 : symbol.startsWith(normalizedQuery) ? 1 : 2;
     };
-    return rank(left) - rank(right);
+    return rank(left) - rank(right) || left.symbol.localeCompare(right.symbol);
   });
-  const quoteAssetCounts = /* @__PURE__ */ new Map();
-  for (const item of rows2) {
-    const quote = text(item.quoteAsset)?.toUpperCase();
-    if (quote) quoteAssetCounts.set(quote, (quoteAssetCounts.get(quote) ?? 0) + 1);
-  }
-  const items = sortedMatches.slice(0, options.limit).map((item) => ({
-    symbol: text(item.SymbolName) ?? text(item.symbol),
-    apiSymbol: text(item.symbol),
-    baseAsset: text(item.baseAssetName) ?? text(item.baseAsset),
-    quoteAsset: text(item.quoteAssetName) ?? text(item.quoteAsset),
-    pricePrecision: item.pricePrecision ?? null,
-    quantityPrecision: item.quantityPrecision ?? null,
-    limitVolumeMin: text(item.limitVolumeMin),
-    limitPriceMin: text(item.limitPriceMin),
-    limitAmountMin: text(item.limitAmountMin)
-  }));
+}
+function summarizeSymbolOverview(value, options) {
+  const rows2 = parsedSymbolRows(value);
   return {
     totalSymbols: rows2.length,
+    quoteAssetCounts: quoteAssetCounts(rows2),
+    sampleSymbols: sortSymbolMatches(rows2).slice(0, options.limit).map((item) => item.symbol)
+  };
+}
+function listSymbols(value, options) {
+  const allRows = parsedSymbolRows(value);
+  const quoteAsset = options.quoteAsset?.trim().toUpperCase();
+  const matches = sortSymbolMatches(allRows.filter((item) => !quoteAsset || item.quoteAsset?.toUpperCase() === quoteAsset));
+  const items = matches.slice(options.offset, options.offset + options.limit).map(basicSymbolItem);
+  const nextOffset = options.offset + items.length;
+  return {
+    totalSymbols: allRows.length,
     matchedSymbols: matches.length,
-    quoteAssetCounts: [...quoteAssetCounts.entries()].sort((left, right) => right[1] - left[1]).map(([asset, count]) => ({ asset, count })),
+    quoteAsset: quoteAsset ?? null,
+    offset: options.offset,
+    limit: options.limit,
+    nextOffset: nextOffset < matches.length ? nextOffset : null,
     items
   };
 }
+function searchSymbols(value, options) {
+  const allRows = parsedSymbolRows(value);
+  const query = options.query.trim().toUpperCase();
+  const quoteAsset = options.quoteAsset?.trim().toUpperCase();
+  const matches = allRows.filter((item) => {
+    const symbol = item.symbol.toUpperCase();
+    const apiSymbol = item.apiSymbol?.toUpperCase() ?? "";
+    return (symbol.includes(query) || apiSymbol.includes(query)) && (!quoteAsset || item.quoteAsset?.toUpperCase() === quoteAsset);
+  });
+  const sortedMatches = sortSymbolMatches(matches, query);
+  return {
+    matchedSymbols: matches.length,
+    query,
+    quoteAsset: quoteAsset ?? null,
+    items: sortedMatches.slice(0, options.limit).map(basicSymbolItem)
+  };
+}
+function getSymbolInfo(value, symbol) {
+  const target = normalizedSymbol(symbol);
+  const item = parsedSymbolRows(value).find((row) => normalizedSymbol(row.symbol) === target || row.apiSymbol !== null && normalizedSymbol(row.apiSymbol) === target);
+  if (!item) throw new AiHubError("AI_HUB_SYMBOL_NOT_FOUND", `Symbol "${symbol}" was not returned by the configured tenant OpenAPI symbols endpoint.`);
+  return fullSymbolItem(item);
+}
 function level(value) {
   if (!Array.isArray(value)) return { price: null, quantity: null };
   return { price: text(value[0]), quantity: text(value[1]) };
@@ -1107,13 +1234,53 @@ function summarizeKlines(value, symbol, interval) {
 }
 
 // ../core/src/tools/symbol-rules.ts
+import { createHash as createHash4 } from "crypto";
+import { chmod as chmod2, mkdir as mkdir2, readFile as readFile2, rename as rename2, rm, writeFile as writeFile2 } from "fs/promises";
+import { homedir as homedir2 } from "os";
+import { join as join2 } from "path";
 var CACHE_TTL_MS = 60 * 60 * 1e3;
 var cache = /* @__PURE__ */ new Map();
 var pendingLoads = /* @__PURE__ */ new Map();
 function cacheKey(context) {
   return `${context.profile.name}\0${context.profile.configVersion}\0${context.profile.openApiBaseUrl}`;
 }
-function normalizedSymbol(symbol) {
+function persistentCacheEnabled() {
+  return process.env.AI_HUB_DISABLE_PERSISTENT_CACHE !== "1";
+}
+function persistentCacheDirectory() {
+  return process.env.AI_HUB_CACHE_DIR ?? join2(homedir2(), ".ai-hub", "cache");
+}
+function persistentCachePath(key) {
+  const hash2 = createHash4("sha256").update(key).digest("hex");
+  return join2(persistentCacheDirectory(), `symbols-${hash2}.json`);
+}
+async function loadPersistentSnapshot(key) {
+  if (!persistentCacheEnabled()) return void 0;
+  try {
+    const parsed = JSON.parse(await readFile2(persistentCachePath(key), "utf8"));
+    if (typeof parsed.expiresAt !== "number" || !Number.isFinite(parsed.expiresAt) || parsed.expiresAt <= Date.now() || !("response" in parsed)) return void 0;
+    return { expiresAt: parsed.expiresAt, response: parsed.response, rules: parseRules(parsed.response) };
+  } catch {
+    return void 0;
+  }
+}
+async function persistSnapshot(key, entry) {
+  if (!persistentCacheEnabled()) return;
+  const directory = persistentCacheDirectory();
+  const filePath = persistentCachePath(key);
+  const temporaryPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    await mkdir2(directory, { recursive: true, mode: 448 });
+    await chmod2(directory, 448);
+    await writeFile2(temporaryPath, JSON.stringify({ expiresAt: entry.expiresAt, response: entry.response }), { mode: 384 });
+    await chmod2(temporaryPath, 384);
+    await rename2(temporaryPath, filePath);
+    await chmod2(filePath, 384);
+  } catch {
+    await rm(temporaryPath, { force: true }).catch(() => void 0);
+  }
+}
+function normalizedSymbol2(symbol) {
   return symbol.replaceAll("/", "").trim().toUpperCase();
 }
 function stringValue(value) {
@@ -1140,7 +1307,7 @@ function parseRules(response) {
   for (const row of rows(response)) {
     const symbol = stringValue(row.symbol);
     if (!symbol) continue;
-    result2.set(normalizedSymbol(symbol), {
+    result2.set(normalizedSymbol2(symbol), {
       symbol,
       quantityPrecision: nonNegativeInteger(row.quantityPrecision),
       pricePrecision: nonNegativeInteger(row.pricePrecision),
@@ -1157,11 +1324,18 @@ async function loadSnapshot(context) {
   if (current && current.expiresAt > Date.now()) return current;
   const pending = pendingLoads.get(key);
   if (pending) return pending;
-  const load = context.api.symbols().then((response) => {
+  const load = (async () => {
+    const persisted = await loadPersistentSnapshot(key);
+    if (persisted) {
+      cache.set(key, persisted);
+      return persisted;
+    }
+    const response = await context.api.symbols();
     const entry = { response, rules: parseRules(response), expiresAt: Date.now() + CACHE_TTL_MS };
     cache.set(key, entry);
+    await persistSnapshot(key, entry);
     return entry;
-  }).finally(() => pendingLoads.delete(key));
+  })().finally(() => pendingLoads.delete(key));
   pendingLoads.set(key, load);
   return load;
 }
@@ -1170,7 +1344,7 @@ async function getCachedSymbols(context) {
 }
 async function getSymbolRule(context, symbol) {
   const entry = await loadSnapshot(context);
-  const rule = entry.rules.get(normalizedSymbol(symbol));
+  const rule = entry.rules.get(normalizedSymbol2(symbol));
   if (!rule) throw new AiHubError("AI_HUB_SYMBOL_NOT_FOUND", `Symbol "${symbol}" was not returned by the configured tenant OpenAPI symbols endpoint.`);
   return rule;
 }
@@ -1227,6 +1401,7 @@ async function preflightSymbolOrder(context, order) {
 
 // ../core/src/tools/market-tools.ts
 var readErrors = ["AI_HUB_INVALID_ARGUMENT", "AI_HUB_OPENAPI_NETWORK_ERROR", "AI_HUB_OPENAPI_HTTP_ERROR", "AI_HUB_OPENAPI_INVALID_RESPONSE", "AI_HUB_OPENAPI_BUSINESS_ERROR"];
+var symbolReadErrors = [...readErrors, "AI_HUB_SYMBOL_NOT_FOUND"];
 var KLINE_INTERVALS = ["1min", "5min", "15min", "30min", "60min", "1day", "1week", "1month"];
 var KLINE_INTERVAL_ALIASES = {
   "1m": "1min",
@@ -1299,7 +1474,7 @@ var marketTools = [
   {
     name: "market_get_symbols",
     title: "Get Spot Symbols",
-    description: "Get complete spot symbol metadata from the configured tenant OpenAPI. Use market_search_symbols for browsing or filtering, because this response may be large.",
+    description: "Get complete spot symbol metadata from the configured tenant OpenAPI. Use market_get_symbol_overview, market_list_symbols, market_search_symbols, or market_get_symbol_info for Agent-facing symbol requests, because this response may be large.",
     cliPath: ["market", "symbols"],
     module: "spot-common",
     access: "public",
@@ -1311,26 +1486,81 @@ var marketTools = [
     validate: (input) => strictObject(input, []),
     handler: (_input, context) => getCachedSymbols(context)
   },
+  {
+    name: "market_get_symbol_overview",
+    title: "Get Spot Symbol Overview",
+    description: "Get a small overview of all configured spot symbols: total count, quote-asset counts, and a bounded sample of display symbols. Use this for generic requests such as listing available trading pairs.",
+    cliPath: ["market", "symbols-overview"],
+    module: "spot-common",
+    access: "public",
+    operation: "read",
+    riskLevel: "low",
+    inputSchema: { type: "object", properties: { limit: { type: "integer", minimum: 1, maximum: 20, description: "Number of sample display symbols. Defaults to 12." } }, additionalProperties: false },
+    errorCodes: readErrors,
+    validate: (input) => {
+      const value = strictObject(input, ["limit"]);
+      return { limit: optionalInteger(value, "limit", 12, 1, 20) };
+    },
+    handler: async (input, context) => summarizeSymbolOverview(await getCachedSymbols(context), input)
+  },
+  {
+    name: "market_list_symbols",
+    title: "List Spot Symbols",
+    description: "List one bounded page of configured spot symbols, optionally restricted to a quote asset. This response excludes precision and trading-rule metadata. Use market_get_symbol_info for one exact symbol's rules.",
+    cliPath: ["market", "symbols-list"],
+    module: "spot-common",
+    access: "public",
+    operation: "read",
+    riskLevel: "low",
+    inputSchema: { type: "object", properties: { quoteAsset: { type: "string" }, offset: { type: "integer", minimum: 0, description: "Zero-based page offset. Defaults to 0." }, limit: { type: "integer", minimum: 1, maximum: 50, description: "Page size. Defaults to 20." } }, additionalProperties: false },
+    errorCodes: readErrors,
+    validate: (input) => {
+      const value = strictObject(input, ["quoteAsset", "offset", "limit"]);
+      return {
+        quoteAsset: optionalString(value, "quoteAsset"),
+        offset: optionalInteger(value, "offset", 0, 0, Number.MAX_SAFE_INTEGER),
+        limit: optionalInteger(value, "limit", 20, 1, 50)
+      };
+    },
+    handler: async (input, context) => listSymbols(await getCachedSymbols(context), input)
+  },
   {
     name: "market_search_symbols",
     title: "Search Spot Symbols",
-    description: "Search the configured tenant's spot symbols and return a bounded metadata result. In MCP, matching rows are at data.value.items. Use this instead of market_get_symbols unless complete raw metadata is explicitly required.",
+    description: "Search configured spot symbols by a required keyword and return a small matching set without trading-rule metadata. Use market_list_symbols for browsing, or market_get_symbol_info for exact precision and minimum rules.",
     cliPath: ["market", "symbols-search"],
     module: "spot-common",
     access: "public",
     operation: "read",
     riskLevel: "low",
-    inputSchema: { type: "object", properties: { query: { type: "string" }, quoteAsset: { type: "string" }, limit: { type: "integer", minimum: 1, maximum: 50 } }, additionalProperties: false },
+    inputSchema: { type: "object", properties: { query: { type: "string", minLength: 1, description: "Required asset or symbol keyword, for example BTC." }, quoteAsset: { type: "string" }, limit: { type: "integer", minimum: 1, maximum: 20 } }, required: ["query"], additionalProperties: false },
     errorCodes: readErrors,
     validate: (input) => {
       const value = strictObject(input, ["query", "quoteAsset", "limit"]);
-      return { query: optionalString(value, "query"), quoteAsset: optionalString(value, "quoteAsset"), limit: optionalInteger(value, "limit", 20, 1, 50) };
+      return { query: requiredString(value, "query"), quoteAsset: optionalString(value, "quoteAsset"), limit: optionalInteger(value, "limit", 10, 1, 20) };
     },
     handler: async (input, context) => {
       const value = input;
-      return summarizeSymbols(await getCachedSymbols(context), value);
+      return searchSymbols(await getCachedSymbols(context), value);
     }
   },
+  {
+    name: "market_get_symbol_info",
+    title: "Get Spot Symbol Information",
+    description: "Get the exact configured spot symbol's trading-rule metadata, including price and quantity precision plus minimum order constraints. Requires an exact symbol such as BTCUSDT or BTC/USDT.",
+    cliPath: ["market", "symbol-info"],
+    module: "spot-common",
+    access: "public",
+    operation: "read",
+    riskLevel: "low",
+    inputSchema: { type: "object", properties: { symbol: { type: "string", minLength: 1 } }, required: ["symbol"], additionalProperties: false },
+    errorCodes: symbolReadErrors,
+    validate: (input) => {
+      const value = strictObject(input, ["symbol"]);
+      return { symbol: requiredString(value, "symbol") };
+    },
+    handler: async (input, context) => getSymbolInfo(await getCachedSymbols(context), input.symbol)
+  },
   {
     name: "market_get_ticker",
     title: "Get Spot Ticker",
@@ -2581,10 +2811,10 @@ function createServer(profileName, readOnly) {
   const registry = createToolRegistry();
   const writeExecutor = new ToolWriteExecutor(registry);
   const server = new Server(
-    { name: "ai-hub-agent-trade", version: "0.1.7" },
+    { name: "ai-hub-agent-trade", version: "0.1.9" },
     {
       capabilities: { tools: {} },
-      instructions: "Every successful read-tool response provides both JSON text and MCP structuredContent in the envelope { ok: true, data: ... }. All read-tool data is normalized: dataType=array means use data.items and data.count; dataType=object or scalar means use data.value; dataType=null means no value. Inspect data.dataType before formatting and never assume undocumented nested keys. For symbol lookup, use market_search_symbols. It returns an object whose bounded matches are at data.value.items; the complete raw symbols payload is intentionally unavailable in MCP. For broad market questions, call market_get_ticker_summary, market_get_depth_summary, market_get_trades_summary, or market_get_klines_summary instead of fetching large raw payloads. Prepare/confirm tools return their documented action payload directly in data. For every state-changing action, call only a spot_prepare_* or margin_prepare_* tool first and show its exact summary to the user. Stop and wait for a new, explicit user confirmation message. Only then call confirm_action with that new message verbatim in userConfirmation. Never call prepare and confirm consecutively for one user instruction; never infer confirmation from prior intent, silence, or an Agent-generated message. For spot and margin orders, MARKET BUY always uses quoteAmount (the quote asset to spend); MARKET SELL uses baseQuantity (the base asset to sell). Never reinterpret a requested base quantity as quoteAmount."
+      instructions: "Every successful read-tool response provides both JSON text and MCP structuredContent in the envelope { ok: true, data: ... }. All read-tool data is normalized: dataType=array means use data.items and data.count; dataType=object or scalar means use data.value; dataType=null means no value. Inspect data.dataType before formatting and never assume undocumented nested keys. For a generic trading-pair list, call market_get_symbol_overview first; it returns only counts and a small sample. For paged or quote-asset browsing, use market_list_symbols. Use market_search_symbols only when the user gave a keyword; query is required. Use market_get_symbol_info only for exact precision and minimum rules. Do not use a symbol search as a generic all-symbol list. The complete raw symbols payload is intentionally unavailable in MCP. For broad market questions, call market_get_ticker_summary, market_get_depth_summary, market_get_trades_summary, or market_get_klines_summary instead of fetching large raw payloads. Account types are fixed: 1=Spot, 2=Isolated Margin, 3=Cross Margin, 4=C2C, 5=Derivatives. Never call account type 2 Derivatives. For Spot to Derivatives, use account_prepare_transfer with fromAccount=EXCHANGE and toAccount=FUTURE. Use wallet_prepare_universal_transfer for margin or C2C; account type 2 requires its isolated-margin trading pair in symbol. Prepare/confirm tools return their documented action payload directly in data. For every state-changing action, call only a spot_prepare_* or margin_prepare_* tool first and show its exact summary to the user. Stop and wait for a new, explicit user confirmation message. Only then call confirm_action with that new message verbatim in userConfirmation. Never call prepare and confirm consecutively for one user instruction; never infer confirmation from prior intent, silence, or an Agent-generated message. For spot and margin orders, MARKET BUY always uses quoteAmount (the quote asset to spend); MARKET SELL uses baseQuantity (the base asset to sell). Never reinterpret a requested base quantity as quoteAmount."
     }
   );
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
@@ -2632,7 +2862,7 @@ function createServer(profileName, readOnly) {
       }
       const tool = registry.byName(request.params.name, { readOnly });
       if (!isMcpVisible(tool)) {
-        throw new AiHubError("AI_HUB_TOOL_NOT_AVAILABLE", `Tool "${request.params.name}" is not available through MCP. Use market_search_symbols for symbol lookup.`);
+        throw new AiHubError("AI_HUB_TOOL_NOT_AVAILABLE", `Tool "${request.params.name}" is not available through MCP. Use market_get_symbol_overview, market_list_symbols, market_search_symbols, or market_get_symbol_info instead.`);
       }
       const data = await registry.execute(request.params.name, request.params.arguments ?? {}, context, { readOnly });
       return toMcpReadResult(formatMcpData(data));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aihubspot/agent-trade-mcp",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Local stdio MCP server for AI Hub spot trading tools",
   "license": "UNLICENSED",
   "repository": {