@okx_ai/okx-trade-mcp 1.2.2 → 1.2.3

package/dist/index.js

@@ -5,6 +5,7 @@ import { parseArgs } from "util";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // ../core/dist/index.js
+import { ProxyAgent } from "undici";
 import { createHmac } from "crypto";
 import fs from "fs";
 import path from "path";
@@ -796,8 +797,10 @@ function sleep(ms) {
 var RateLimiter = class {
   buckets = /* @__PURE__ */ new Map();
   maxWaitMs;
-  constructor(maxWaitMs = 3e4) {
+  verbose;
+  constructor(maxWaitMs = 3e4, verbose = false) {
     this.maxWaitMs = maxWaitMs;
+    this.verbose = verbose;
   }
   async consume(config, amount = 1) {
     const bucket = this.getBucket(config);
@@ -815,6 +818,10 @@ var RateLimiter = class {
         "Reduce tool call frequency or retry later."
       );
     }
+    if (this.verbose) {
+      process.stderr.write(`[verbose] \u23F3 rate-limit: waiting ${waitMs}ms for "${config.key}"
+`);
+    }
     await sleep(waitMs);
     this.refill(bucket);
     if (bucket.tokens < amount) {
@@ -909,11 +916,38 @@ function buildQueryString(query) {
   }
   return params.toString();
 }
+function maskKey(key) {
+  if (key.length <= 8) return "***";
+  return `${key.slice(0, 3)}***${key.slice(-3)}`;
+}
+function vlog(message) {
+  process.stderr.write(`[verbose] ${message}
+`);
+}
 var OkxRestClient = class {
   config;
-  rateLimiter = new RateLimiter();
+  rateLimiter;
+  dispatcher;
   constructor(config) {
     this.config = config;
+    this.rateLimiter = new RateLimiter(3e4, config.verbose);
+    if (config.proxyUrl) {
+      this.dispatcher = new ProxyAgent(config.proxyUrl);
+    }
+  }
+  logRequest(method, url, auth) {
+    if (!this.config.verbose) return;
+    vlog(`\u2192 ${method} ${url}`);
+    const authInfo = auth === "private" && this.config.apiKey ? `auth=\u2713(${maskKey(this.config.apiKey)})` : `auth=${auth}`;
+    vlog(`  ${authInfo} demo=${this.config.demo} timeout=${this.config.timeoutMs}ms`);
+  }
+  logResponse(status, rawLen, elapsed, traceId, code, msg) {
+    if (!this.config.verbose) return;
+    if (code && code !== "0" && code !== "1") {
+      vlog(`\u2717 ${status} | code=${code} | msg=${msg ?? "-"} | ${rawLen}B | ${elapsed}ms | trace=${traceId ?? "-"}`);
+    } else {
+      vlog(`\u2190 ${status} | code=${code ?? "0"} | ${rawLen}B | ${elapsed}ms | trace=${traceId ?? "-"}`);
+    }
   }
   async publicGet(path4, query, rateLimit) {
     return this.request({
@@ -942,126 +976,150 @@ var OkxRestClient = class {
       rateLimit
     });
   }
-  async request(config) {
-    const queryString = buildQueryString(config.query);
-    const requestPath = queryString.length > 0 ? `${config.path}?${queryString}` : config.path;
-    const url = `${this.config.baseUrl}${requestPath}`;
-    const bodyJson = config.body ? JSON.stringify(config.body) : "";
-    const timestamp = getNow();
-    if (config.rateLimit) {
-      await this.rateLimiter.consume(config.rateLimit);
-    }
-    const headers = new Headers({
-      "Content-Type": "application/json",
-      Accept: "application/json"
-    });
-    if (this.config.userAgent) {
-      headers.set("User-Agent", this.config.userAgent);
-    }
-    if (config.auth === "private") {
-      if (!this.config.hasAuth) {
-        throw new ConfigError(
-          "Private endpoint requires API credentials.",
-          "Configure OKX_API_KEY, OKX_SECRET_KEY and OKX_PASSPHRASE."
-        );
-      }
-      if (!this.config.apiKey || !this.config.secretKey || !this.config.passphrase) {
-        throw new ConfigError(
-          "Invalid private API credentials state.",
-          "Ensure all OKX credentials are set."
-        );
-      }
-      const payload = `${timestamp}${config.method.toUpperCase()}${requestPath}${bodyJson}`;
-      const signature = signOkxPayload(payload, this.config.secretKey);
-      headers.set("OK-ACCESS-KEY", this.config.apiKey);
-      headers.set("OK-ACCESS-SIGN", signature);
-      headers.set("OK-ACCESS-PASSPHRASE", this.config.passphrase);
-      headers.set("OK-ACCESS-TIMESTAMP", timestamp);
+  setAuthHeaders(headers, method, requestPath, bodyJson, timestamp) {
+    if (!this.config.hasAuth) {
+      throw new ConfigError(
+        "Private endpoint requires API credentials.",
+        "Configure OKX_API_KEY, OKX_SECRET_KEY and OKX_PASSPHRASE."
+      );
     }
-    if (this.config.demo) {
-      headers.set("x-simulated-trading", "1");
+    if (!this.config.apiKey || !this.config.secretKey || !this.config.passphrase) {
+      throw new ConfigError(
+        "Invalid private API credentials state.",
+        "Ensure all OKX credentials are set."
+      );
     }
-    let response;
-    try {
-      response = await fetch(url, {
-        method: config.method,
-        headers,
-        body: config.method === "POST" ? bodyJson : void 0,
-        signal: AbortSignal.timeout(this.config.timeoutMs)
-      });
-    } catch (error) {
-      throw new NetworkError(
-        `Failed to call OKX endpoint ${config.method} ${requestPath}.`,
-        `${config.method} ${requestPath}`,
-        error
+    const payload = `${timestamp}${method.toUpperCase()}${requestPath}${bodyJson}`;
+    const signature = signOkxPayload(payload, this.config.secretKey);
+    headers.set("OK-ACCESS-KEY", this.config.apiKey);
+    headers.set("OK-ACCESS-SIGN", signature);
+    headers.set("OK-ACCESS-PASSPHRASE", this.config.passphrase);
+    headers.set("OK-ACCESS-TIMESTAMP", timestamp);
+  }
+  throwOkxError(code, msg, reqConfig, traceId) {
+    const message = msg || "OKX API request failed.";
+    const endpoint = `${reqConfig.method} ${reqConfig.path}`;
+    if (code === "50111" || code === "50112" || code === "50113") {
+      throw new AuthenticationError(
+        message,
+        "Check API key, secret, passphrase and permissions.",
+        endpoint,
+        traceId
       );
     }
-    const rawText = await response.text();
-    const traceId = extractTraceId(response.headers);
+    const behavior = OKX_CODE_BEHAVIORS[code];
+    const suggestion = behavior?.suggestion?.replace("{site}", this.config.site);
+    if (code === "50011" || code === "50061") {
+      throw new RateLimitError(message, suggestion, endpoint, traceId);
+    }
+    throw new OkxApiError(message, {
+      code,
+      endpoint,
+      suggestion,
+      traceId
+    });
+  }
+  processResponse(rawText, response, elapsed, traceId, reqConfig, requestPath) {
     let parsed;
     try {
       parsed = rawText ? JSON.parse(rawText) : {};
     } catch (error) {
+      this.logResponse(response.status, rawText.length, elapsed, traceId, "non-JSON");
       if (!response.ok) {
         const messagePreview = rawText.slice(0, 160).replace(/\s+/g, " ").trim();
         throw new OkxApiError(
           `HTTP ${response.status} from OKX: ${messagePreview || "Non-JSON response body"}`,
           {
             code: String(response.status),
-            endpoint: `${config.method} ${config.path}`,
+            endpoint: `${reqConfig.method} ${reqConfig.path}`,
             suggestion: "Verify endpoint path and request parameters.",
             traceId
           }
         );
       }
       throw new NetworkError(
-        `OKX returned non-JSON response for ${config.method} ${requestPath}.`,
-        `${config.method} ${requestPath}`,
+        `OKX returned non-JSON response for ${reqConfig.method} ${requestPath}.`,
+        `${reqConfig.method} ${requestPath}`,
         error
       );
     }
     if (!response.ok) {
+      this.logResponse(response.status, rawText.length, elapsed, traceId, parsed.code ?? "-", parsed.msg);
       throw new OkxApiError(
         `HTTP ${response.status} from OKX: ${parsed.msg ?? "Unknown error"}`,
         {
           code: String(response.status),
-          endpoint: `${config.method} ${config.path}`,
+          endpoint: `${reqConfig.method} ${reqConfig.path}`,
           suggestion: "Retry later or verify endpoint parameters.",
           traceId
         }
       );
     }
     const responseCode = parsed.code;
+    this.logResponse(response.status, rawText.length, elapsed, traceId, responseCode, parsed.msg);
     if (responseCode && responseCode !== "0" && responseCode !== "1") {
-      const message = parsed.msg || "OKX API request failed.";
-      const endpoint = `${config.method} ${config.path}`;
-      if (responseCode === "50111" || responseCode === "50112" || responseCode === "50113") {
-        throw new AuthenticationError(
-          message,
-          "Check API key, secret, passphrase and permissions.",
-          endpoint,
-          traceId
-        );
-      }
-      const behavior = OKX_CODE_BEHAVIORS[responseCode];
-      const suggestion = behavior?.suggestion?.replace("{site}", this.config.site);
-      if (responseCode === "50011" || responseCode === "50061") {
-        throw new RateLimitError(message, suggestion, endpoint, traceId);
-      }
-      throw new OkxApiError(message, {
-        code: responseCode,
-        endpoint,
-        suggestion,
-        traceId
-      });
+      this.throwOkxError(responseCode, parsed.msg, reqConfig, traceId);
     }
     return {
-      endpoint: `${config.method} ${config.path}`,
+      endpoint: `${reqConfig.method} ${reqConfig.path}`,
       requestTime: (/* @__PURE__ */ new Date()).toISOString(),
       data: parsed.data ?? null,
       raw: parsed
     };
   }
+  async request(reqConfig) {
+    const queryString = buildQueryString(reqConfig.query);
+    const requestPath = queryString.length > 0 ? `${reqConfig.path}?${queryString}` : reqConfig.path;
+    const url = `${this.config.baseUrl}${requestPath}`;
+    const bodyJson = reqConfig.body ? JSON.stringify(reqConfig.body) : "";
+    const timestamp = getNow();
+    this.logRequest(reqConfig.method, url, reqConfig.auth);
+    if (reqConfig.rateLimit) {
+      await this.rateLimiter.consume(reqConfig.rateLimit);
+    }
+    const headers = new Headers({
+      "Content-Type": "application/json",
+      Accept: "application/json"
+    });
+    if (this.config.userAgent) {
+      headers.set("User-Agent", this.config.userAgent);
+    }
+    if (reqConfig.auth === "private") {
+      this.setAuthHeaders(headers, reqConfig.method, requestPath, bodyJson, timestamp);
+    }
+    if (this.config.demo) {
+      headers.set("x-simulated-trading", "1");
+    }
+    const t0 = Date.now();
+    let response;
+    try {
+      const fetchOptions = {
+        method: reqConfig.method,
+        headers,
+        body: reqConfig.method === "POST" ? bodyJson : void 0,
+        signal: AbortSignal.timeout(this.config.timeoutMs)
+      };
+      if (this.dispatcher) {
+        fetchOptions.dispatcher = this.dispatcher;
+      }
+      response = await fetch(url, fetchOptions);
+    } catch (error) {
+      if (this.config.verbose) {
+        const elapsed2 = Date.now() - t0;
+        const cause = error instanceof Error ? error.message : String(error);
+        vlog(`\u2717 NetworkError after ${elapsed2}ms: ${cause}`);
+      }
+      throw new NetworkError(
+        `Failed to call OKX endpoint ${reqConfig.method} ${requestPath}.`,
+        `${reqConfig.method} ${requestPath}`,
+        error
+      );
+    }
+    const rawText = await response.text();
+    const elapsed = Date.now() - t0;
+    const traceId = extractTraceId(response.headers);
+    return this.processResponse(rawText, response, elapsed, traceId, reqConfig, requestPath);
+  }
 };
 var DEFAULT_SOURCE_TAG = "MCP";
 var OKX_SITES = {
@@ -1087,6 +1145,10 @@ var BOT_SUB_MODULE_IDS = [
   "bot.dca"
 ];
 var BOT_DEFAULT_SUB_MODULES = ["bot.grid"];
+var EARN_SUB_MODULE_IDS = [
+  "earn.savings",
+  "earn.onchain"
+];
 var MODULES = [
   "market",
   "spot",
@@ -1094,6 +1156,7 @@ var MODULES = [
   "futures",
   "option",
   "account",
+  ...EARN_SUB_MODULE_IDS,
   ...BOT_SUB_MODULE_IDS
 ];
 var DEFAULT_MODULES = ["spot", "swap", "option", "account", ...BOT_DEFAULT_SUB_MODULES];
@@ -1159,6 +1222,13 @@ function compactObject(object) {
   }
   return next;
 }
+function normalizeResponse(response) {
+  return {
+    endpoint: response.endpoint,
+    requestTime: response.requestTime,
+    data: response.data
+  };
+}
 var OKX_CANDLE_BARS = [
   "1m",
   "3m",
@@ -1198,6 +1268,14 @@ function privateRateLimit(key, rps = 10) {
     refillPerSecond: rps
   };
 }
+function assertNotDemo(config, endpoint) {
+  if (config.demo) {
+    throw new ConfigError(
+      `"${endpoint}" is not supported in simulated trading mode.`,
+      "Disable demo mode (remove OKX_DEMO=1 or --demo flag) to use this endpoint."
+    );
+  }
+}
 function normalize(response) {
   return {
     endpoint: response.endpoint,
@@ -1776,7 +1854,7 @@ function registerAlgoTradeTools() {
           },
           sz: {
             type: "string",
-            description: "Contracts to close"
+            description: "Number of contracts to close (NOT USDT amount). Use market_get_instruments to get ctVal for conversion."
           },
           tpTriggerPx: {
             type: "string",
@@ -1871,7 +1949,7 @@ function registerAlgoTradeTools() {
           },
           sz: {
             type: "string",
-            description: "Contracts"
+            description: "Number of contracts (NOT USDT amount). Use market_get_instruments to get ctVal for conversion."
           },
           callbackRatio: {
             type: "string",
@@ -2684,6 +2762,246 @@ function registerBotTools() {
     ...registerDcaTools()
   ];
 }
+function registerEarnTools() {
+  return [
+    {
+      name: "earn_get_savings_balance",
+      module: "earn.savings",
+      description: "Get Simple Earn (savings/flexible earn) balance. Returns current holdings for all currencies or a specific one. Private endpoint. Rate limit: 6 req/s.",
+      isWrite: false,
+      inputSchema: {
+        type: "object",
+        properties: {
+          ccy: {
+            type: "string",
+            description: "e.g. USDT or BTC. Omit for all."
+          }
+        }
+      },
+      handler: async (rawArgs, context) => {
+        const args = asRecord(rawArgs);
+        const response = await context.client.privateGet(
+          "/api/v5/finance/savings/balance",
+          compactObject({ ccy: readString(args, "ccy") }),
+          privateRateLimit("earn_get_savings_balance", 6)
+        );
+        return normalizeResponse(response);
+      }
+    },
+    {
+      name: "earn_savings_purchase",
+      module: "earn.savings",
+      description: "Purchase Simple Earn (savings/flexible earn). [CAUTION] Moves real funds into earn product. Not supported in demo/simulated trading mode. Private endpoint. Rate limit: 6 req/s.",
+      isWrite: true,
+      inputSchema: {
+        type: "object",
+        properties: {
+          ccy: {
+            type: "string",
+            description: "Currency to purchase, e.g. USDT"
+          },
+          amt: {
+            type: "string",
+            description: "Purchase amount"
+          },
+          rate: {
+            type: "string",
+            description: "Lending rate. Annual rate in decimal, e.g. 0.01 = 1%. Defaults to 0.01 (1%, minimum rate, easiest to match)."
+          }
+        },
+        required: ["ccy", "amt"]
+      },
+      handler: async (rawArgs, context) => {
+        assertNotDemo(context.config, "earn_savings_purchase");
+        const args = asRecord(rawArgs);
+        const response = await context.client.privatePost(
+          "/api/v5/finance/savings/purchase-redempt",
+          compactObject({
+            ccy: requireString(args, "ccy"),
+            amt: requireString(args, "amt"),
+            side: "purchase",
+            rate: readString(args, "rate") ?? "0.01"
+          }),
+          privateRateLimit("earn_savings_purchase", 6)
+        );
+        return normalizeResponse(response);
+      }
+    },
+    {
+      name: "earn_savings_redeem",
+      module: "earn.savings",
+      description: "Redeem Simple Earn (savings/flexible earn). [CAUTION] Withdraws funds from earn product. Not supported in demo/simulated trading mode. Private endpoint. Rate limit: 6 req/s.",
+      isWrite: true,
+      inputSchema: {
+        type: "object",
+        properties: {
+          ccy: {
+            type: "string",
+            description: "Currency to redeem, e.g. USDT"
+          },
+          amt: {
+            type: "string",
+            description: "Redemption amount"
+          }
+        },
+        required: ["ccy", "amt"]
+      },
+      handler: async (rawArgs, context) => {
+        assertNotDemo(context.config, "earn_savings_redeem");
+        const args = asRecord(rawArgs);
+        const response = await context.client.privatePost(
+          "/api/v5/finance/savings/purchase-redempt",
+          compactObject({
+            ccy: requireString(args, "ccy"),
+            amt: requireString(args, "amt"),
+            side: "redempt"
+          }),
+          privateRateLimit("earn_savings_redeem", 6)
+        );
+        return normalizeResponse(response);
+      }
+    },
+    {
+      name: "earn_set_lending_rate",
+      module: "earn.savings",
+      description: "Set lending rate for Simple Earn. [CAUTION] Changes your lending rate preference. Not supported in demo/simulated trading mode. Private endpoint. Rate limit: 6 req/s.",
+      isWrite: true,
+      inputSchema: {
+        type: "object",
+        properties: {
+          ccy: {
+            type: "string",
+            description: "Currency, e.g. USDT"
+          },
+          rate: {
+            type: "string",
+            description: "Lending rate. Annual rate in decimal, e.g. 0.01 = 1%"
+          }
+        },
+        required: ["ccy", "rate"]
+      },
+      handler: async (rawArgs, context) => {
+        assertNotDemo(context.config, "earn_set_lending_rate");
+        const args = asRecord(rawArgs);
+        const response = await context.client.privatePost(
+          "/api/v5/finance/savings/set-lending-rate",
+          {
+            ccy: requireString(args, "ccy"),
+            rate: requireString(args, "rate")
+          },
+          privateRateLimit("earn_set_lending_rate", 6)
+        );
+        return normalizeResponse(response);
+      }
+    },
+    {
+      name: "earn_get_lending_history",
+      module: "earn.savings",
+      description: "Get lending history for Simple Earn. Returns lending records with details like amount, rate, and earnings. Private endpoint. Rate limit: 6 req/s.",
+      isWrite: false,
+      inputSchema: {
+        type: "object",
+        properties: {
+          ccy: {
+            type: "string",
+            description: "e.g. USDT. Omit for all."
+          },
+          after: {
+            type: "string",
+            description: "Pagination: before this record ID"
+          },
+          before: {
+            type: "string",
+            description: "Pagination: after this record ID"
+          },
+          limit: {
+            type: "number",
+            description: "Max results (default 100)"
+          }
+        }
+      },
+      handler: async (rawArgs, context) => {
+        const args = asRecord(rawArgs);
+        const response = await context.client.privateGet(
+          "/api/v5/finance/savings/lending-history",
+          compactObject({
+            ccy: readString(args, "ccy"),
+            after: readString(args, "after"),
+            before: readString(args, "before"),
+            limit: readNumber(args, "limit")
+          }),
+          privateRateLimit("earn_get_lending_history", 6)
+        );
+        return normalizeResponse(response);
+      }
+    },
+    {
+      name: "earn_get_lending_rate_summary",
+      module: "earn.savings",
+      description: "Get market lending rate summary for Simple Earn. Public endpoint (no API key required). Returns current lending rates, estimated APY, and available amounts. Rate limit: 6 req/s.",
+      isWrite: false,
+      inputSchema: {
+        type: "object",
+        properties: {
+          ccy: {
+            type: "string",
+            description: "e.g. USDT. Omit for all."
+          }
+        }
+      },
+      handler: async (rawArgs, context) => {
+        const args = asRecord(rawArgs);
+        const response = await context.client.publicGet(
+          "/api/v5/finance/savings/lending-rate-summary",
+          compactObject({ ccy: readString(args, "ccy") }),
+          publicRateLimit("earn_get_lending_rate_summary", 6)
+        );
+        return normalizeResponse(response);
+      }
+    },
+    {
+      name: "earn_get_lending_rate_history",
+      module: "earn.savings",
+      description: "Get historical lending rates for Simple Earn. Public endpoint (no API key required). Returns past lending rate data for trend analysis. Rate limit: 6 req/s.",
+      isWrite: false,
+      inputSchema: {
+        type: "object",
+        properties: {
+          ccy: {
+            type: "string",
+            description: "e.g. USDT. Omit for all."
+          },
+          after: {
+            type: "string",
+            description: "Pagination: before this timestamp (ms)"
+          },
+          before: {
+            type: "string",
+            description: "Pagination: after this timestamp (ms)"
+          },
+          limit: {
+            type: "number",
+            description: "Max results (default 100)"
+          }
+        }
+      },
+      handler: async (rawArgs, context) => {
+        const args = asRecord(rawArgs);
+        const response = await context.client.publicGet(
+          "/api/v5/finance/savings/lending-rate-history",
+          compactObject({
+            ccy: readString(args, "ccy"),
+            after: readString(args, "after"),
+            before: readString(args, "before"),
+            limit: readNumber(args, "limit")
+          }),
+          publicRateLimit("earn_get_lending_rate_history", 6)
+        );
+        return normalizeResponse(response);
+      }
+    }
+  ];
+}
 var FUTURES_INST_TYPES = ["FUTURES", "SWAP"];
 function normalize5(response) {
   return {
@@ -2728,7 +3046,7 @@ function registerFuturesTools() {
           },
           sz: {
             type: "string",
-            description: "Contracts"
+            description: "Number of contracts (NOT USDT amount). Use market_get_instruments to get ctVal for conversion."
           },
           px: {
             type: "string",
@@ -3049,6 +3367,278 @@ function registerFuturesTools() {
     }
   ];
 }
+function registerOnchainEarnTools() {
+  return [
+    // -------------------------------------------------------------------------
+    // Get Offers
+    // -------------------------------------------------------------------------
+    {
+      name: "onchain_earn_get_offers",
+      module: "earn.onchain",
+      description: "Get available on-chain earn (staking/DeFi) offers. Returns investment products with APY, terms, and limits. Private endpoint. Rate limit: 3 req/s.",
+      isWrite: false,
+      inputSchema: {
+        type: "object",
+        properties: {
+          productId: {
+            type: "string",
+            description: "Specific product ID to query. Omit for all offers."
+          },
+          protocolType: {
+            type: "string",
+            description: "Protocol type filter: staking, defi. Omit for all types."
+          },
+          ccy: {
+            type: "string",
+            description: "Currency filter, e.g. ETH. Omit for all currencies."
+          }
+        }
+      },
+      handler: async (rawArgs, context) => {
+        const args = asRecord(rawArgs);
+        const response = await context.client.privateGet(
+          "/api/v5/finance/staking-defi/offers",
+          compactObject({
+            productId: readString(args, "productId"),
+            protocolType: readString(args, "protocolType"),
+            ccy: readString(args, "ccy")
+          }),
+          privateRateLimit("onchain_earn_get_offers", 3)
+        );
+        return normalizeResponse(response);
+      }
+    },
+    // -------------------------------------------------------------------------
+    // Purchase
+    // -------------------------------------------------------------------------
+    {
+      name: "onchain_earn_purchase",
+      module: "earn.onchain",
+      description: "Purchase on-chain earn (staking/DeFi) product. [CAUTION] Moves real funds into staking/DeFi product. Not supported in demo/simulated trading mode. Private endpoint. Rate limit: 2 req/s.",
+      isWrite: true,
+      inputSchema: {
+        type: "object",
+        properties: {
+          productId: {
+            type: "string",
+            description: "Product ID to purchase"
+          },
+          investData: {
+            type: "array",
+            description: "Investment data array: [{ccy, amt}]. Each item specifies currency and amount.",
+            items: {
+              type: "object",
+              properties: {
+                ccy: { type: "string", description: "Currency, e.g. ETH" },
+                amt: { type: "string", description: "Amount to invest" }
+              },
+              required: ["ccy", "amt"]
+            }
+          },
+          term: {
+            type: "string",
+            description: "Investment term in days. Required for fixed-term products."
+          },
+          tag: {
+            type: "string",
+            description: "Order tag for tracking (optional)."
+          }
+        },
+        required: ["productId", "investData"]
+      },
+      handler: async (rawArgs, context) => {
+        assertNotDemo(context.config, "onchain_earn_purchase");
+        const args = asRecord(rawArgs);
+        const response = await context.client.privatePost(
+          "/api/v5/finance/staking-defi/purchase",
+          compactObject({
+            productId: requireString(args, "productId"),
+            investData: args.investData,
+            term: readString(args, "term"),
+            tag: readString(args, "tag")
+          }),
+          privateRateLimit("onchain_earn_purchase", 2)
+        );
+        return normalizeResponse(response);
+      }
+    },
+    // -------------------------------------------------------------------------
+    // Redeem
+    // -------------------------------------------------------------------------
+    {
+      name: "onchain_earn_redeem",
+      module: "earn.onchain",
+      description: "Redeem on-chain earn (staking/DeFi) investment. [CAUTION] Withdraws funds from staking/DeFi product. Some products may have lock periods. Not supported in demo mode. Private endpoint. Rate limit: 2 req/s.",
+      isWrite: true,
+      inputSchema: {
+        type: "object",
+        properties: {
+          ordId: {
+            type: "string",
+            description: "Order ID to redeem"
+          },
+          protocolType: {
+            type: "string",
+            description: "Protocol type: staking, defi"
+          },
+          allowEarlyRedeem: {
+            type: "boolean",
+            description: "Allow early redemption for fixed-term products (may incur penalties). Default false."
+          }
+        },
+        required: ["ordId", "protocolType"]
+      },
+      handler: async (rawArgs, context) => {
+        assertNotDemo(context.config, "onchain_earn_redeem");
+        const args = asRecord(rawArgs);
+        const response = await context.client.privatePost(
+          "/api/v5/finance/staking-defi/redeem",
+          compactObject({
+            ordId: requireString(args, "ordId"),
+            protocolType: requireString(args, "protocolType"),
+            allowEarlyRedeem: readBoolean(args, "allowEarlyRedeem")
+          }),
+          privateRateLimit("onchain_earn_redeem", 2)
+        );
+        return normalizeResponse(response);
+      }
+    },
+    // -------------------------------------------------------------------------
+    // Cancel
+    // -------------------------------------------------------------------------
+    {
+      name: "onchain_earn_cancel",
+      module: "earn.onchain",
+      description: "Cancel pending on-chain earn purchase. [CAUTION] Cancels a pending investment order. Not supported in demo mode. Private endpoint. Rate limit: 2 req/s.",
+      isWrite: true,
+      inputSchema: {
+        type: "object",
+        properties: {
+          ordId: {
+            type: "string",
+            description: "Order ID to cancel"
+          },
+          protocolType: {
+            type: "string",
+            description: "Protocol type: staking, defi"
+          }
+        },
+        required: ["ordId", "protocolType"]
+      },
+      handler: async (rawArgs, context) => {
+        assertNotDemo(context.config, "onchain_earn_cancel");
+        const args = asRecord(rawArgs);
+        const response = await context.client.privatePost(
+          "/api/v5/finance/staking-defi/cancel",
+          {
+            ordId: requireString(args, "ordId"),
+            protocolType: requireString(args, "protocolType")
+          },
+          privateRateLimit("onchain_earn_cancel", 2)
+        );
+        return normalizeResponse(response);
+      }
+    },
+    // -------------------------------------------------------------------------
+    // Get Active Orders
+    // -------------------------------------------------------------------------
+    {
+      name: "onchain_earn_get_active_orders",
+      module: "earn.onchain",
+      description: "Get active on-chain earn orders. Returns current staking/DeFi investments. Private endpoint. Rate limit: 3 req/s.",
+      isWrite: false,
+      inputSchema: {
+        type: "object",
+        properties: {
+          productId: {
+            type: "string",
+            description: "Filter by product ID. Omit for all."
+          },
+          protocolType: {
+            type: "string",
+            description: "Filter by protocol type: staking, defi. Omit for all."
+          },
+          ccy: {
+            type: "string",
+            description: "Filter by currency, e.g. ETH. Omit for all."
+          },
+          state: {
+            type: "string",
+            description: "Filter by state: 8 (pending), 13 (cancelling), 9 (onchain), 1 (earning), 2 (redeeming). Omit for all."
+          }
+        }
+      },
+      handler: async (rawArgs, context) => {
+        const args = asRecord(rawArgs);
+        const response = await context.client.privateGet(
+          "/api/v5/finance/staking-defi/orders-active",
+          compactObject({
+            productId: readString(args, "productId"),
+            protocolType: readString(args, "protocolType"),
+            ccy: readString(args, "ccy"),
+            state: readString(args, "state")
+          }),
+          privateRateLimit("onchain_earn_get_active_orders", 3)
+        );
+        return normalizeResponse(response);
+      }
+    },
+    // -------------------------------------------------------------------------
+    // Get Order History
+    // -------------------------------------------------------------------------
+    {
+      name: "onchain_earn_get_order_history",
+      module: "earn.onchain",
+      description: "Get on-chain earn order history. Returns past staking/DeFi investments including redeemed orders. Private endpoint. Rate limit: 3 req/s.",
+      isWrite: false,
+      inputSchema: {
+        type: "object",
+        properties: {
+          productId: {
+            type: "string",
+            description: "Filter by product ID. Omit for all."
+          },
+          protocolType: {
+            type: "string",
+            description: "Filter by protocol type: staking, defi. Omit for all."
+          },
+          ccy: {
+            type: "string",
+            description: "Filter by currency, e.g. ETH. Omit for all."
+          },
+          after: {
+            type: "string",
+            description: "Pagination: return results before this order ID"
+          },
+          before: {
+            type: "string",
+            description: "Pagination: return results after this order ID"
+          },
+          limit: {
+            type: "string",
+            description: "Max results to return (default 100, max 100)"
+          }
+        }
+      },
+      handler: async (rawArgs, context) => {
+        const args = asRecord(rawArgs);
+        const response = await context.client.privateGet(
+          "/api/v5/finance/staking-defi/orders-history",
+          compactObject({
+            productId: readString(args, "productId"),
+            protocolType: readString(args, "protocolType"),
+            ccy: readString(args, "ccy"),
+            after: readString(args, "after"),
+            before: readString(args, "before"),
+            limit: readString(args, "limit")
+          }),
+          privateRateLimit("onchain_earn_get_order_history", 3)
+        );
+        return normalizeResponse(response);
+      }
+    }
+  ];
+}
 function normalize6(response) {
   return {
     endpoint: response.endpoint,
@@ -3566,7 +4156,7 @@ function registerOptionTools() {
           },
           sz: {
             type: "string",
-            description: "Number of contracts"
+            description: "Number of contracts (NOT USDT amount). Use market_get_instruments to get ctVal for conversion."
           },
           px: {
             type: "string",
@@ -3673,7 +4263,7 @@ function registerOptionTools() {
           instId: { type: "string", description: "e.g. BTC-USD-241227-50000-C" },
           ordId: { type: "string" },
           clOrdId: { type: "string" },
-          newSz: { type: "string", description: "New quantity (contracts)" },
+          newSz: { type: "string", description: "New number of contracts (NOT USDT amount)" },
           newPx: { type: "string", description: "New price" }
         },
         required: ["instId"]
@@ -4635,7 +5225,7 @@ function registerSwapTradeTools() {
           },
           sz: {
             type: "string",
-            description: "Contracts (e.g. '1'; BTC-USDT-SWAP: 1ct=0.01 BTC)"
+            description: "Number of contracts (NOT USDT amount). Use market_get_instruments to get ctVal for conversion."
           },
           px: {
             type: "string",
@@ -4900,7 +5490,7 @@ function registerSwapTradeTools() {
         properties: {
           instId: { type: "string", description: "e.g. BTC-USDT-SWAP" },
           algoId: { type: "string", description: "Algo order ID" },
-          newSz: { type: "string", description: "New quantity (contracts)" },
+          newSz: { type: "string", description: "New number of contracts (NOT USDT amount)" },
           newTpTriggerPx: { type: "string", description: "New TP trigger price" },
           newTpOrdPx: { type: "string", description: "New TP order price; -1=market" },
           newSlTriggerPx: { type: "string", description: "New SL trigger price" },
@@ -5253,6 +5843,8 @@ function allToolSpecs() {
     ...registerAlgoTradeTools(),
     ...registerAccountTools(),
     ...registerBotTools(),
+    ...registerEarnTools(),
+    ...registerOnchainEarnTools(),
     ...registerAuditTools()
   ];
 }
@@ -5292,8 +5884,15 @@ function readTomlProfile(profileName) {
   return config.profiles?.[name] ?? {};
 }
 var BASE_MODULES = MODULES.filter(
-  (m) => !BOT_SUB_MODULE_IDS.includes(m)
+  (m) => !BOT_SUB_MODULE_IDS.includes(m) && !EARN_SUB_MODULE_IDS.includes(m)
 );
+function expandShorthand(moduleId) {
+  if (moduleId === "all") return [...BASE_MODULES, ...BOT_SUB_MODULE_IDS];
+  if (moduleId === "earn" || moduleId === "earn.all") return [...EARN_SUB_MODULE_IDS];
+  if (moduleId === "bot") return [...BOT_DEFAULT_SUB_MODULES];
+  if (moduleId === "bot.all") return [...BOT_SUB_MODULE_IDS];
+  return null;
+}
 function parseModuleList(rawModules) {
   if (!rawModules || rawModules.trim().length === 0) {
     return [...DEFAULT_MODULES];
@@ -5302,32 +5901,28 @@ function parseModuleList(rawModules) {
   if (trimmed === "all") {
     return [...BASE_MODULES, ...BOT_SUB_MODULE_IDS];
   }
-  const requested = trimmed.split(",").map((item) => item.trim()).filter((item) => item.length > 0);
+  const requested = trimmed.split(",").map((s) => s.trim()).filter(Boolean);
   if (requested.length === 0) {
     return [...DEFAULT_MODULES];
   }
   const deduped = /* @__PURE__ */ new Set();
   for (const moduleId of requested) {
-    if (moduleId === "bot") {
-      for (const sub of BOT_DEFAULT_SUB_MODULES) deduped.add(sub);
-      continue;
-    }
-    if (moduleId === "bot.all") {
-      for (const sub of BOT_SUB_MODULE_IDS) deduped.add(sub);
+    const expanded = expandShorthand(moduleId);
+    if (expanded) {
+      expanded.forEach((sub) => deduped.add(sub));
       continue;
     }
     if (!MODULES.includes(moduleId)) {
       throw new ConfigError(
         `Unknown module "${moduleId}".`,
-        `Use one of: ${MODULES.join(", ")}, "bot", "bot.all", or "all".`
+        `Use one of: ${MODULES.join(", ")}, "earn", "earn.all", "bot", "bot.all", or "all".`
       );
     }
     deduped.add(moduleId);
   }
   return Array.from(deduped);
 }
-function loadConfig(cli) {
-  const toml = readTomlProfile(cli.profile);
+function loadCredentials(toml) {
   const apiKey = process.env.OKX_API_KEY?.trim() ?? toml.api_key;
   const secretKey = process.env.OKX_SECRET_KEY?.trim() ?? toml.secret_key;
   const passphrase = process.env.OKX_PASSPHRASE?.trim() ?? toml.passphrase;
@@ -5339,23 +5934,34 @@ function loadConfig(cli) {
       "Set OKX_API_KEY, OKX_SECRET_KEY and OKX_PASSPHRASE together (env vars or config.toml profile)."
     );
   }
-  const demo = cli.demo || process.env.OKX_DEMO === "1" || process.env.OKX_DEMO === "true" || (toml.demo ?? false);
-  const rawSite = cli.site?.trim() ?? process.env.OKX_SITE?.trim() ?? toml.site ?? "global";
+  return { apiKey, secretKey, passphrase, hasAuth };
+}
+function resolveSite(cliSite, tomlSite) {
+  const rawSite = cliSite?.trim() ?? process.env.OKX_SITE?.trim() ?? tomlSite ?? "global";
   if (!SITE_IDS.includes(rawSite)) {
     throw new ConfigError(
       `Unknown site "${rawSite}".`,
       `Use one of: ${SITE_IDS.join(", ")}.`
     );
   }
-  const site = rawSite;
-  const rawBaseUrl = process.env.OKX_API_BASE_URL?.trim() ?? toml.base_url ?? OKX_SITES[site].apiBaseUrl;
+  return rawSite;
+}
+function resolveBaseUrl(site, tomlBaseUrl) {
+  const rawBaseUrl = process.env.OKX_API_BASE_URL?.trim() ?? tomlBaseUrl ?? OKX_SITES[site].apiBaseUrl;
   if (!rawBaseUrl.startsWith("http://") && !rawBaseUrl.startsWith("https://")) {
     throw new ConfigError(
       `Invalid base URL "${rawBaseUrl}".`,
       "OKX_API_BASE_URL must start with http:// or https://"
     );
   }
-  const baseUrl = rawBaseUrl.replace(/\/+$/, "");
+  return rawBaseUrl.replace(/\/+$/, "");
+}
+function loadConfig(cli) {
+  const toml = readTomlProfile(cli.profile);
+  const creds = loadCredentials(toml);
+  const demo = cli.demo || process.env.OKX_DEMO === "1" || process.env.OKX_DEMO === "true" || (toml.demo ?? false);
+  const site = resolveSite(cli.site, toml.site);
+  const baseUrl = resolveBaseUrl(site, toml.base_url);
   const rawTimeout = process.env.OKX_TIMEOUT_MS ? Number(process.env.OKX_TIMEOUT_MS) : toml.timeout_ms ?? 15e3;
   if (!Number.isFinite(rawTimeout) || rawTimeout <= 0) {
     throw new ConfigError(
@@ -5363,11 +5969,15 @@ function loadConfig(cli) {
       "Set OKX_TIMEOUT_MS as a positive integer in milliseconds."
     );
   }
+  const rawProxyUrl = toml.proxy_url?.trim();
+  if (rawProxyUrl && !rawProxyUrl.startsWith("http://") && !rawProxyUrl.startsWith("https://")) {
+    throw new ConfigError(
+      `Invalid proxy URL "${rawProxyUrl}".`,
+      "proxy_url must start with http:// or https://. SOCKS proxies are not supported."
+    );
+  }
   return {
-    apiKey,
-    secretKey,
-    passphrase,
-    hasAuth,
+    ...creds,
     baseUrl,
     timeoutMs: Math.floor(rawTimeout),
     modules: parseModuleList(cli.modules),
@@ -5375,7 +5985,9 @@ function loadConfig(cli) {
     demo,
     site,
     userAgent: cli.userAgent,
-    sourceTag: cli.sourceTag ?? DEFAULT_SOURCE_TAG
+    sourceTag: cli.sourceTag ?? DEFAULT_SOURCE_TAG,
+    proxyUrl: rawProxyUrl || void 0,
+    verbose: cli.verbose ?? false
   };
 }
 var CACHE_FILE = join2(homedir2(), ".okx", "update-check.json");
@@ -5660,7 +6272,7 @@ var _require = createRequire(import.meta.url);
 var pkg = _require("../package.json");
 var SERVER_NAME = "okx-trade-mcp";
 var SERVER_VERSION = pkg.version;
-var GIT_HASH = true ? "c49054f" : "dev";
+var GIT_HASH = true ? "4427916" : "dev";
 
 // src/server.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";