toobit-trade-cli 1.0.1 → 1.0.2

package/dist/index.js

@@ -167,7 +167,9 @@ var TOOBIT_CODE_BEHAVIORS = {
   "-2013": { retry: false, suggestion: "Order does not exist." },
   "-2014": { retry: false, suggestion: "Bad API key format." },
   "-2015": { retry: false, suggestion: "Invalid API key, IP, or permission." },
-  "-2017": { retry: false, suggestion: "API key expired. Generate a new one." }
+  "-2017": { retry: false, suggestion: "API key expired. Generate a new one." },
+  "-1130": { retry: false, suggestion: "Invalid symbol format. Futures endpoints require BTC-SWAP-USDT format; spot endpoints use BTCUSDT." },
+  "-1107": { retry: false, suggestion: "API key is missing or malformed. Check X-BB-APIKEY header." }
 };
 function isDefined(value) {
   return value !== void 0 && value !== null;
@@ -285,34 +287,42 @@ var ToobitRestClient = class {
         `${config.method} ${config.path}`
       );
     }
-    if (!response.ok) {
-      throw new ToobitApiError(
-        `HTTP ${response.status} from Toobit: ${parsed.msg ?? "Unknown error"}`,
-        { code: String(response.status), endpoint: `${config.method} ${config.path}` }
-      );
-    }
     const responseCode = parsed.code;
-    if (responseCode !== void 0 && responseCode !== 0) {
-      const message = parsed.msg || "Toobit API request failed.";
-      const endpoint = `${config.method} ${config.path}`;
+    const responseMsg = parsed.msg || void 0;
+    const endpoint = `${config.method} ${config.path}`;
+    const hasBusinessCode = responseCode !== void 0 && responseCode !== 0;
+    if (hasBusinessCode) {
       const codeStr = String(responseCode);
-      if (codeStr === "-1002" || codeStr === "-1022" || codeStr === "-2014" || codeStr === "-2015") {
+      const message = responseMsg || "Toobit API request failed.";
+      const behavior = TOOBIT_CODE_BEHAVIORS[codeStr];
+      if (codeStr === "-1002" || codeStr === "-1022" || codeStr === "-1107" || codeStr === "-2014" || codeStr === "-2015" || codeStr === "-2017") {
         throw new AuthenticationError(
           message,
-          "Check API key, secret key and permissions.",
+          behavior?.suggestion ?? "Check API key, secret key and permissions.",
           endpoint
         );
       }
       if (codeStr === "-1003") {
         throw new RateLimitError(message, "Too many requests. Back off.", endpoint);
       }
-      const behavior = TOOBIT_CODE_BEHAVIORS[codeStr];
       throw new ToobitApiError(message, {
         code: codeStr,
         endpoint,
         suggestion: behavior?.suggestion
       });
     }
+    if (!response.ok) {
+      const rawMsg = responseMsg ?? "Unknown error";
+      let suggestion;
+      if (/symbol|paramter|parameter/i.test(rawMsg)) {
+        const isFuturesPath = /futures|fundingRate|openInterest|markPrice|contract|longShort|insurance|riskLimit/i.test(config.path);
+        suggestion = isFuturesPath ? "Futures endpoints require contract symbol format, e.g. BTC-SWAP-USDT instead of BTCUSDT." : "Spot endpoints require symbol format like BTCUSDT.";
+      }
+      throw new ToobitApiError(
+        `HTTP ${response.status} from Toobit: ${rawMsg}`,
+        { code: String(response.status), endpoint, suggestion }
+      );
+    }
     return {
       endpoint: `${config.method} ${config.path}`,
       requestTime: (/* @__PURE__ */ new Date()).toISOString(),
@@ -1298,6 +1308,13 @@ function registerFuturesTools() {
     }
   ];
 }
+function readPositiveInt(args, key) {
+  const value = readNumber(args, key);
+  if (value !== void 0 && value < 1) {
+    throw new ValidationError(`Parameter "${key}" must be a positive integer.`);
+  }
+  return value;
+}
 function normalize3(response) {
   return { endpoint: response.endpoint, requestTime: response.requestTime, data: response.data };
 }
@@ -1342,7 +1359,7 @@ function registerMarketTools() {
         const args = asRecord(rawArgs);
         const response = await context.client.publicGet(
           "/quote/v1/depth",
-          compactObject({ symbol: requireString(args, "symbol"), limit: readNumber(args, "limit") }),
+          compactObject({ symbol: requireString(args, "symbol"), limit: readPositiveInt(args, "limit") }),
           publicRateLimit("market_get_depth", 20)
         );
         return normalize3(response);
@@ -1366,7 +1383,7 @@ function registerMarketTools() {
         const args = asRecord(rawArgs);
         const response = await context.client.publicGet(
           "/quote/v1/depth/merged",
-          compactObject({ symbol: requireString(args, "symbol"), scale: readNumber(args, "scale"), limit: readNumber(args, "limit") }),
+          compactObject({ symbol: requireString(args, "symbol"), scale: readNumber(args, "scale"), limit: readPositiveInt(args, "limit") }),
           publicRateLimit("market_get_merged_depth", 20)
         );
         return normalize3(response);
@@ -1389,7 +1406,7 @@ function registerMarketTools() {
         const args = asRecord(rawArgs);
         const response = await context.client.publicGet(
           "/quote/v1/trades",
-          compactObject({ symbol: requireString(args, "symbol"), limit: readNumber(args, "limit") }),
+          compactObject({ symbol: requireString(args, "symbol"), limit: readPositiveInt(args, "limit") }),
           publicRateLimit("market_get_trades", 20)
         );
         return normalize3(response);
@@ -1420,7 +1437,7 @@ function registerMarketTools() {
             interval: requireString(args, "interval"),
             startTime: readNumber(args, "startTime"),
             endTime: readNumber(args, "endTime"),
-            limit: readNumber(args, "limit")
+            limit: readPositiveInt(args, "limit")
           }),
           publicRateLimit("market_get_klines", 20)
         );
@@ -1430,12 +1447,12 @@ function registerMarketTools() {
     {
       name: "market_get_ticker_24hr",
       module: "market",
-      description: "Get 24h price change statistics for a spot symbol. Public endpoint. Rate limit: 20 req/s.",
+      description: "Get 24h price change statistics for a spot symbol. Omitting symbol returns ALL symbols (900+). Always specify a symbol unless you need the full list. Public endpoint. Rate limit: 20 req/s.",
       isWrite: false,
       inputSchema: {
         type: "object",
         properties: {
-          symbol: { type: "string", description: "e.g. BTCUSDT. Omit for all symbols." }
+          symbol: { type: "string", description: "e.g. BTCUSDT. Omit for all symbols (warning: 900+ results)." }
         }
       },
       handler: async (rawArgs, context) => {
@@ -1451,12 +1468,12 @@ function registerMarketTools() {
     {
       name: "market_get_ticker_price",
       module: "market",
-      description: "Get latest price for a spot symbol. Public endpoint. Rate limit: 20 req/s.",
+      description: "Get latest price for a spot symbol. Omitting symbol returns ALL symbols (900+), which may consume many tokens. Always specify a symbol unless you need the full list. Public endpoint. Rate limit: 20 req/s.",
       isWrite: false,
       inputSchema: {
         type: "object",
         properties: {
-          symbol: { type: "string", description: "e.g. BTCUSDT. Omit for all symbols." }
+          symbol: { type: "string", description: "e.g. BTCUSDT. Omit for all symbols (warning: 900+ results)." }
         }
       },
       handler: async (rawArgs, context) => {
@@ -1472,12 +1489,12 @@ function registerMarketTools() {
     {
       name: "market_get_book_ticker",
       module: "market",
-      description: "Get best bid/ask price for a spot symbol. Public endpoint. Rate limit: 20 req/s.",
+      description: "Get best bid/ask price for a spot symbol. Omitting symbol returns ALL symbols. Always specify a symbol unless you need the full list. Public endpoint. Rate limit: 20 req/s.",
       isWrite: false,
       inputSchema: {
         type: "object",
         properties: {
-          symbol: { type: "string", description: "e.g. BTCUSDT. Omit for all symbols." }
+          symbol: { type: "string", description: "e.g. BTCUSDT. Omit for all symbols (warning: 900+ results)." }
         }
       },
       handler: async (rawArgs, context) => {
@@ -1515,7 +1532,7 @@ function registerMarketTools() {
             interval: requireString(args, "interval"),
             startTime: readNumber(args, "startTime"),
             endTime: readNumber(args, "endTime"),
-            limit: readNumber(args, "limit")
+            limit: readPositiveInt(args, "limit")
           }),
           publicRateLimit("market_get_index_klines", 20)
         );
@@ -1525,12 +1542,12 @@ function registerMarketTools() {
     {
       name: "market_get_mark_price",
       module: "market",
-      description: "Get latest mark price for a futures symbol. Public endpoint. Rate limit: 20 req/s.",
+      description: "Get latest mark price for a futures symbol. Requires contract symbol format. Public endpoint. Rate limit: 20 req/s.",
       isWrite: false,
       inputSchema: {
         type: "object",
         properties: {
-          symbol: { type: "string", description: "e.g. BTCUSDT. Omit for all." }
+          symbol: { type: "string", description: "Futures contract symbol, e.g. BTC-SWAP-USDT. Omit for all." }
         }
       },
       handler: async (rawArgs, context) => {
@@ -1546,12 +1563,12 @@ function registerMarketTools() {
     {
       name: "market_get_mark_price_klines",
       module: "market",
-      description: "Get mark price K-line data. Public endpoint. Rate limit: 20 req/s.",
+      description: "Get mark price K-line data. Requires contract symbol format. Public endpoint. Rate limit: 20 req/s.",
       isWrite: false,
       inputSchema: {
         type: "object",
         properties: {
-          symbol: { type: "string", description: "e.g. BTCUSDT" },
+          symbol: { type: "string", description: "Futures contract symbol, e.g. BTC-SWAP-USDT" },
           interval: { type: "string", enum: [...TOOBIT_CANDLE_BARS] },
           startTime: { type: "number" },
           endTime: { type: "number" },
@@ -1568,7 +1585,7 @@ function registerMarketTools() {
             interval: requireString(args, "interval"),
             startTime: readNumber(args, "startTime"),
             endTime: readNumber(args, "endTime"),
-            limit: readNumber(args, "limit")
+            limit: readPositiveInt(args, "limit")
           }),
           publicRateLimit("market_get_mark_price_klines", 20)
         );
@@ -1578,12 +1595,12 @@ function registerMarketTools() {
     {
       name: "market_get_funding_rate",
       module: "market",
-      description: "Get current funding rate for a futures symbol. Public endpoint. Rate limit: 20 req/s.",
+      description: "Get current funding rate for a futures symbol. Requires contract symbol format. Public endpoint. Rate limit: 20 req/s.",
       isWrite: false,
       inputSchema: {
         type: "object",
         properties: {
-          symbol: { type: "string", description: "e.g. BTCUSDT. Omit for all." }
+          symbol: { type: "string", description: "Futures contract symbol, e.g. BTC-SWAP-USDT. Omit for all." }
         }
       },
       handler: async (rawArgs, context) => {
@@ -1599,12 +1616,12 @@ function registerMarketTools() {
     {
       name: "market_get_funding_rate_history",
       module: "market",
-      description: "Get historical funding rates for a futures symbol. Public endpoint. Rate limit: 20 req/s.",
+      description: "Get historical funding rates for a futures symbol. Requires contract symbol format. Public endpoint. Rate limit: 20 req/s.",
       isWrite: false,
       inputSchema: {
         type: "object",
         properties: {
-          symbol: { type: "string", description: "e.g. BTCUSDT" },
+          symbol: { type: "string", description: "Futures contract symbol, e.g. BTC-SWAP-USDT" },
           startTime: { type: "number" },
           endTime: { type: "number" },
           limit: { type: "number", description: "Default 100, max 1000" }
@@ -1619,7 +1636,7 @@ function registerMarketTools() {
             symbol: requireString(args, "symbol"),
             startTime: readNumber(args, "startTime"),
             endTime: readNumber(args, "endTime"),
-            limit: readNumber(args, "limit")
+            limit: readPositiveInt(args, "limit")
           }),
           publicRateLimit("market_get_funding_rate_history", 20)
         );
@@ -1629,12 +1646,12 @@ function registerMarketTools() {
     {
       name: "market_get_open_interest",
       module: "market",
-      description: "Get total open interest for a futures symbol. Public endpoint. Rate limit: 20 req/s.",
+      description: "Get total open interest for a futures symbol. Requires contract symbol format. Public endpoint. Rate limit: 20 req/s.",
       isWrite: false,
       inputSchema: {
         type: "object",
         properties: {
-          symbol: { type: "string", description: "e.g. BTCUSDT. Omit for all." }
+          symbol: { type: "string", description: "Futures contract symbol, e.g. BTC-SWAP-USDT. Omit for all." }
         }
       },
       handler: async (rawArgs, context) => {
@@ -1655,7 +1672,7 @@ function registerMarketTools() {
       inputSchema: {
         type: "object",
         properties: {
-          symbol: { type: "string", description: "e.g. BTCUSDT" },
+          symbol: { type: "string", description: "Futures contract symbol, e.g. BTC-SWAP-USDT" },
           period: { type: "string", description: "e.g. 5m, 15m, 30m, 1h, 2h, 4h, 6h, 12h, 1d" },
           startTime: { type: "number" },
           endTime: { type: "number" },
@@ -1672,7 +1689,7 @@ function registerMarketTools() {
             period: requireString(args, "period"),
             startTime: readNumber(args, "startTime"),
             endTime: readNumber(args, "endTime"),
-            limit: readNumber(args, "limit")
+            limit: readPositiveInt(args, "limit")
           }),
           publicRateLimit("market_get_long_short_ratio", 20)
         );
@@ -1682,12 +1699,12 @@ function registerMarketTools() {
     {
       name: "market_get_contract_ticker_24hr",
       module: "market",
-      description: "Get 24h price change statistics for a futures contract. Public endpoint. Rate limit: 20 req/s.",
+      description: "Get 24h price change statistics for a futures contract. Requires contract symbol format. Public endpoint. Rate limit: 20 req/s.",
       isWrite: false,
       inputSchema: {
         type: "object",
         properties: {
-          symbol: { type: "string", description: "e.g. BTCUSDT. Omit for all." }
+          symbol: { type: "string", description: "Futures contract symbol, e.g. BTC-SWAP-USDT. Omit for all." }
         }
       },
       handler: async (rawArgs, context) => {
@@ -1703,12 +1720,12 @@ function registerMarketTools() {
     {
       name: "market_get_contract_ticker_price",
       module: "market",
-      description: "Get latest price for a futures contract. Public endpoint. Rate limit: 20 req/s.",
+      description: "Get latest price for a futures contract. Supports both spot (BTCUSDT) and contract (BTC-SWAP-USDT) symbol formats. Public endpoint. Rate limit: 20 req/s.",
       isWrite: false,
       inputSchema: {
         type: "object",
         properties: {
-          symbol: { type: "string", description: "e.g. BTCUSDT. Omit for all." }
+          symbol: { type: "string", description: "e.g. BTC-SWAP-USDT or BTCUSDT. Omit for all." }
         }
       },
       handler: async (rawArgs, context) => {
@@ -1745,12 +1762,12 @@ function registerMarketTools() {
     {
       name: "market_get_insurance_fund",
       module: "market",
-      description: "Get insurance fund balance for a symbol. Public endpoint. Rate limit: 20 req/s.",
+      description: "Get insurance fund balance for a futures symbol. Requires contract symbol format. Public endpoint. Rate limit: 20 req/s.",
       isWrite: false,
       inputSchema: {
         type: "object",
         properties: {
-          symbol: { type: "string", description: "e.g. BTCUSDT" }
+          symbol: { type: "string", description: "Futures contract symbol, e.g. BTC-SWAP-USDT" }
         },
         required: ["symbol"]
       },
@@ -1767,12 +1784,12 @@ function registerMarketTools() {
     {
       name: "market_get_risk_limits",
       module: "market",
-      description: "Get risk limits configuration for a futures symbol. Public endpoint. Rate limit: 20 req/s.",
+      description: "Get risk limits configuration for a futures symbol. Requires contract symbol format. Public endpoint. Rate limit: 20 req/s.",
       isWrite: false,
       inputSchema: {
         type: "object",
         properties: {
-          symbol: { type: "string", description: "e.g. BTCUSDT" }
+          symbol: { type: "string", description: "Futures contract symbol, e.g. BTC-SWAP-USDT" }
         },
         required: ["symbol"]
       },
@@ -2078,12 +2095,15 @@ function allToolSpecs() {
   ];
 }
 function createToolRunner(client, config) {
-  const fullConfig = { ...config, modules: [...MODULES], readOnly: false };
+  const fullConfig = { ...config, modules: [...MODULES] };
   const tools = allToolSpecs();
   const toolMap = new Map(tools.map((t) => [t.name, t]));
   return async (toolName, args) => {
     const tool = toolMap.get(toolName);
     if (!tool) throw new Error(`Unknown tool: ${toolName}`);
+    if (config.readOnly && tool.isWrite) {
+      throw new Error(`Tool "${toolName}" is a write operation and is blocked in read-only mode.`);
+    }
     const result = await tool.handler(args, { config: fullConfig, client });
     return result;
   };
@@ -2264,11 +2284,58 @@ function parseCli(argv = process.argv.slice(2)) {
 }
 
 // src/formatter.ts
+function extractRows(value) {
+  if (Array.isArray(value)) return value;
+  if (typeof value === "object" && value !== null) {
+    const entries = Object.values(value);
+    for (const v of entries) {
+      if (Array.isArray(v)) return v;
+    }
+  }
+  return null;
+}
 function formatJson(data, json) {
   if (json) return JSON.stringify(data, null, 2);
   if (data === null || data === void 0) return "No data.";
   if (typeof data !== "object") return String(data);
-  return JSON.stringify(data, null, 2);
+  const record = data;
+  const inner = record.data ?? record;
+  const rows = extractRows(inner);
+  if (rows) {
+    if (rows.length === 0) return "No data.";
+    if (typeof rows[0] === "object" && rows[0] !== null) {
+      return formatTable(rows);
+    }
+    return rows.map(String).join("\n");
+  }
+  if (typeof inner === "object" && inner !== null) {
+    return formatKv(inner);
+  }
+  return String(inner);
+}
+function formatKv(data) {
+  const entries = Object.entries(data).filter(([, v]) => v !== void 0 && v !== null);
+  if (entries.length === 0) return "No data.";
+  const maxKey = Math.max(...entries.map(([k]) => k.length));
+  return entries.map(([k, v]) => {
+    if (typeof v === "object") return `${k.padEnd(maxKey)}  ${JSON.stringify(v)}`;
+    return `${k.padEnd(maxKey)}  ${String(v)}`;
+  }).join("\n");
+}
+function formatTable(rows, columns) {
+  if (rows.length === 0) return "No data.";
+  const keys = columns ?? Object.keys(rows[0]);
+  const widths = keys.map(
+    (k) => Math.max(k.length, ...rows.map((r) => String(r[k] ?? "").length))
+  );
+  const header = keys.map((k, i) => k.padEnd(widths[i])).join("  ");
+  const separator = widths.map((w) => "-".repeat(w)).join("  ");
+  const body = rows.map(
+    (row) => keys.map((k, i) => String(row[k] ?? "").padEnd(widths[i])).join("  ")
+  ).join("\n");
+  return `${header}
+${separator}
+${body}`;
 }
 
 // src/commands/market.ts
@@ -2331,9 +2398,18 @@ async function handleMarketCommand(cli, run) {
     case "long-short-ratio":
       result = await run("market_get_long_short_ratio", { symbol: f.symbol, period: f.period ?? "1h" });
       break;
+    case "contract-ticker-price":
+      result = await run("market_get_contract_ticker_price", { symbol: f.symbol });
+      break;
+    case "insurance-fund":
+      result = await run("market_get_insurance_fund", { symbol: f.symbol });
+      break;
+    case "risk-limits":
+      result = await run("market_get_risk_limits", { symbol: f.symbol });
+      break;
     default:
       process.stdout.write(`Unknown market subcommand: ${cli.subcommand}
-Available: time, info, ticker, ticker-24hr, depth, trades, klines, candles, book-ticker, mark-price, funding-rate, funding-rate-history, open-interest, index, contract-ticker, long-short-ratio
+Available: time, info, ticker, ticker-24hr, depth, trades, klines, candles, book-ticker, mark-price, funding-rate, funding-rate-history, open-interest, index, contract-ticker, contract-ticker-price, long-short-ratio, insurance-fund, risk-limits
 `);
       return;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toobit-trade-cli",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "type": "module",
   "bin": {
     "toobit": "dist/index.js"

package/src/commands/market.ts

@@ -62,8 +62,17 @@ export async function handleMarketCommand(cli: CliParsed, run: ToolRunner): Prom
     case "long-short-ratio":
       result = await run("market_get_long_short_ratio", { symbol: f.symbol, period: f.period ?? "1h" });
       break;
+    case "contract-ticker-price":
+      result = await run("market_get_contract_ticker_price", { symbol: f.symbol });
+      break;
+    case "insurance-fund":
+      result = await run("market_get_insurance_fund", { symbol: f.symbol });
+      break;
+    case "risk-limits":
+      result = await run("market_get_risk_limits", { symbol: f.symbol });
+      break;
     default:
-      process.stdout.write(`Unknown market subcommand: ${cli.subcommand}\nAvailable: time, info, ticker, ticker-24hr, depth, trades, klines, candles, book-ticker, mark-price, funding-rate, funding-rate-history, open-interest, index, contract-ticker, long-short-ratio\n`);
+      process.stdout.write(`Unknown market subcommand: ${cli.subcommand}\nAvailable: time, info, ticker, ticker-24hr, depth, trades, klines, candles, book-ticker, mark-price, funding-rate, funding-rate-history, open-interest, index, contract-ticker, contract-ticker-price, long-short-ratio, insurance-fund, risk-limits\n`);
       return;
   }
 

package/src/formatter.ts

@@ -1,8 +1,46 @@
+function extractRows(value: unknown): unknown[] | null {
+  if (Array.isArray(value)) return value;
+  if (typeof value === "object" && value !== null) {
+    const entries = Object.values(value as Record<string, unknown>);
+    for (const v of entries) {
+      if (Array.isArray(v)) return v;
+    }
+  }
+  return null;
+}
+
 export function formatJson(data: unknown, json: boolean): string {
   if (json) return JSON.stringify(data, null, 2);
   if (data === null || data === undefined) return "No data.";
   if (typeof data !== "object") return String(data);
-  return JSON.stringify(data, null, 2);
+
+  const record = data as Record<string, unknown>;
+  const inner = record.data ?? record;
+
+  const rows = extractRows(inner);
+  if (rows) {
+    if (rows.length === 0) return "No data.";
+    if (typeof rows[0] === "object" && rows[0] !== null) {
+      return formatTable(rows as Record<string, unknown>[]);
+    }
+    return rows.map(String).join("\n");
+  }
+
+  if (typeof inner === "object" && inner !== null) {
+    return formatKv(inner as Record<string, unknown>);
+  }
+
+  return String(inner);
+}
+
+export function formatKv(data: Record<string, unknown>): string {
+  const entries = Object.entries(data).filter(([, v]) => v !== undefined && v !== null);
+  if (entries.length === 0) return "No data.";
+  const maxKey = Math.max(...entries.map(([k]) => k.length));
+  return entries.map(([k, v]) => {
+    if (typeof v === "object") return `${k.padEnd(maxKey)}  ${JSON.stringify(v)}`;
+    return `${k.padEnd(maxKey)}  ${String(v)}`;
+  }).join("\n");
 }
 
 export function formatTable(rows: Record<string, unknown>[], columns?: string[]): string {