@okx_ai/okx-trade-mcp 1.3.0 → 1.3.1-beta.2

package/dist/index.js

@@ -1248,6 +1248,9 @@ function readNumber(args, key) {
   if (value === void 0 || value === null) {
     return void 0;
   }
+  if (typeof value === "string" && /^-?\d+(\.\d+)?$/.test(value)) {
+    return parseFloat(value);
+  }
   if (typeof value !== "number" || Number.isNaN(value)) {
     throw new ValidationError(`Parameter "${key}" must be a number.`);
   }
@@ -1327,7 +1330,8 @@ var OKX_INST_TYPES = [
   "SWAP",
   "FUTURES",
   "OPTION",
-  "MARGIN"
+  "MARGIN",
+  "EVENTS"
 ];
 function publicRateLimit(key, rps = 20) {
   return {
@@ -1625,6 +1629,7 @@ var MODULES = [
   "futures",
   "option",
   "account",
+  "event",
   ...EARN_SUB_MODULE_IDS,
   ...BOT_SUB_MODULE_IDS,
   "skills"
@@ -1818,7 +1823,7 @@ function registerAccountTools() {
         properties: {
           instType: {
             type: "string",
-            enum: ["SPOT", "MARGIN", "SWAP", "FUTURES", "OPTION"]
+            enum: ["SPOT", "MARGIN", "SWAP", "FUTURES", "OPTION", "EVENTS"]
           },
           ccy: {
             type: "string",
@@ -1884,7 +1889,7 @@ function registerAccountTools() {
         properties: {
           instType: {
             type: "string",
-            enum: ["SWAP", "FUTURES", "MARGIN", "OPTION"],
+            enum: ["SWAP", "FUTURES", "MARGIN", "OPTION", "EVENTS"],
             description: "Default SWAP"
           },
           instId: {
@@ -1945,7 +1950,7 @@ function registerAccountTools() {
         properties: {
           instType: {
             type: "string",
-            enum: ["SPOT", "MARGIN", "SWAP", "FUTURES", "OPTION"]
+            enum: ["SPOT", "MARGIN", "SWAP", "FUTURES", "OPTION", "EVENTS"]
           },
           instId: {
             type: "string",
@@ -2056,14 +2061,14 @@ function registerAccountTools() {
     {
       name: "account_get_positions",
       module: "account",
-      description: "Get current open positions across all instrument types (MARGIN, SWAP, FUTURES, OPTION). Use swap_get_positions for SWAP/FUTURES-only queries.",
+      description: "Get current open positions across all instrument types (MARGIN, SWAP, FUTURES, OPTION, EVENTS). Use swap_get_positions for SWAP/FUTURES-only queries.",
       isWrite: false,
       inputSchema: {
         type: "object",
         properties: {
           instType: {
             type: "string",
-            enum: ["MARGIN", "SWAP", "FUTURES", "OPTION"]
+            enum: ["MARGIN", "SWAP", "FUTURES", "OPTION", "EVENTS"]
           },
           instId: {
             type: "string",
@@ -4817,6 +4822,765 @@ function registerAllEarnTools() {
   ];
   return tools.map(withDemoGuard);
 }
+function findDateIdx(parts) {
+  for (let i = 1; i < parts.length; i++) {
+    if (/^\d{6}$/.test(parts[i])) return i;
+  }
+  return -1;
+}
+function inferExpiryMsFromInstId(instId) {
+  const parts = instId.split("-");
+  const upper = instId.toUpperCase();
+  const dateIdx = findDateIdx(parts);
+  if (dateIdx < 0) return null;
+  const dp = parts[dateIdx];
+  const year = 2e3 + parseInt(dp.slice(0, 2), 10);
+  const month = parseInt(dp.slice(2, 4), 10) - 1;
+  const day = parseInt(dp.slice(4, 6), 10);
+  const isUpDown = upper.includes("UPDOWN");
+  let timePart;
+  if (isUpDown) {
+    const candidate = parts[dateIdx + 2];
+    timePart = candidate && /^\d{4}$/.test(candidate) ? candidate : parts[dateIdx + 1];
+  } else {
+    timePart = parts[dateIdx + 1];
+  }
+  if (!timePart || !/^\d{4}$/.test(timePart)) return null;
+  const hour = parseInt(timePart.slice(0, 2), 10);
+  const min = parseInt(timePart.slice(2, 4), 10);
+  return Date.UTC(year, month, day, hour - 8, min, 0, 0);
+}
+function extractSeriesId(instId) {
+  const parts = instId.split("-");
+  for (let i = 0; i < parts.length; i++) {
+    if (/^\d{6}$/.test(parts[i])) {
+      return parts.slice(0, i).join("-");
+    }
+  }
+  return instId;
+}
+function fmtTimeToken(t) {
+  return t.length === 4 ? `${t.slice(0, 2)}:${t.slice(2)}` : t;
+}
+function fmtUpDownName(seriesId, dateStr, parts, dateIdx) {
+  const t1 = parts[dateIdx + 1] ?? "";
+  const t2 = parts[dateIdx + 2] ?? "";
+  const timeRange = t1 && t2 ? ` ${fmtTimeToken(t1)}-${fmtTimeToken(t2)}` : "";
+  return `${seriesId} Up/Down \xB7 ${dateStr}${timeRange}`;
+}
+function fmtStrikeName(seriesId, dateStr, label, parts, dateIdx) {
+  const strike = parts[dateIdx + 2] ?? "";
+  const strikeStr = strike && /^\d+$/.test(strike) ? Number(strike).toLocaleString("en-US") : "";
+  return strikeStr ? `${seriesId} ${label} ${strikeStr} \xB7 ${dateStr}` : `${seriesId} \xB7 ${dateStr}`;
+}
+function formatDisplayTitle(instId) {
+  const parts = instId.split("-");
+  const upper = instId.toUpperCase();
+  const seriesId = parts[0] ?? instId;
+  const dateIdx = findDateIdx(parts);
+  if (dateIdx < 0) return instId;
+  const d = parts[dateIdx];
+  const month = parseInt(d.slice(2, 4), 10);
+  const day = parseInt(d.slice(4, 6), 10);
+  const dateStr = `${month}/${day}`;
+  if (upper.includes("UPDOWN") || upper.includes("UP-DOWN")) {
+    return fmtUpDownName(seriesId, dateStr, parts, dateIdx);
+  }
+  if (upper.includes("ABOVE")) {
+    return fmtStrikeName(seriesId, dateStr, "above", parts, dateIdx);
+  }
+  if (upper.includes("TOUCH")) {
+    return fmtStrikeName(seriesId, dateStr, "touch", parts, dateIdx);
+  }
+  return `${seriesId} \xB7 ${dateStr}`;
+}
+var OUTCOME_LABELS = {
+  "0": "pending",
+  "1": "YES",
+  "2": "NO"
+};
+var ORDER_STATE_MAP = {
+  live: "Unfilled",
+  partially_filled: "Partially filled",
+  filled: "Filled",
+  canceled: "Canceled",
+  mmp_canceled: "Canceled"
+};
+function mapOrderState(raw) {
+  return ORDER_STATE_MAP[raw] ?? raw;
+}
+var TIMESTAMP_FIELDS = /* @__PURE__ */ new Set([
+  "expTime",
+  "settleTime",
+  "listTime",
+  "uTime",
+  "cTime",
+  "fixTime"
+]);
+var DEFAULT_SETTLE_CCY = "USDT";
+function convertTimestamps(item) {
+  const result = { ...item };
+  for (const key of TIMESTAMP_FIELDS) {
+    if (!(key in result)) continue;
+    const v = Number(result[key]);
+    if (v > 0) {
+      const d = new Date(v + 8 * 60 * 60 * 1e3);
+      const yyyy = d.getUTCFullYear();
+      const mo = String(d.getUTCMonth() + 1).padStart(2, "0");
+      const dd = String(d.getUTCDate()).padStart(2, "0");
+      const hh = String(d.getUTCHours()).padStart(2, "0");
+      const mi = String(d.getUTCMinutes()).padStart(2, "0");
+      result[key] = `${yyyy}-${mo}-${dd} ${hh}:${mi} UTC+8`;
+    } else {
+      delete result[key];
+    }
+  }
+  return result;
+}
+function normalizeWrite3(response) {
+  const data = response.data;
+  if (Array.isArray(data) && data.length > 0) {
+    const failed = data.filter(
+      (item) => item !== null && typeof item === "object" && "sCode" in item && item["sCode"] !== "0"
+    );
+    if (failed.length > 0) {
+      const messages = failed.map(
+        (item) => `[${item["sCode"]}] ${item["sMsg"] ?? "Operation failed"}`
+      );
+      throw new OkxApiError(messages.join("; "), {
+        code: String(failed[0]["sCode"] ?? ""),
+        endpoint: response.endpoint
+      });
+    }
+  }
+  return { endpoint: response.endpoint, requestTime: response.requestTime, data };
+}
+function extractQuoteCcy(underlying) {
+  if (!underlying) return DEFAULT_SETTLE_CCY;
+  const parts = underlying.split("-");
+  return parts.length >= 2 ? parts[parts.length - 1].toUpperCase() : DEFAULT_SETTLE_CCY;
+}
+async function fetchAvailableBalance(client, ccy = DEFAULT_SETTLE_CCY) {
+  try {
+    const r = await client.privateGet(
+      "/api/v5/account/balance",
+      { ccy }
+    );
+    const data = r["data"];
+    if (Array.isArray(data) && data.length > 0) {
+      const details = data[0]["details"];
+      if (Array.isArray(details) && details.length > 0) {
+        const entry = details.find(
+          (d) => String(d["ccy"] ?? "").toUpperCase() === ccy.toUpperCase()
+        );
+        if (!entry) return { balance: null, ccy };
+        const bal = String(entry["availBal"] ?? "") || null;
+        return { balance: bal, ccy };
+      }
+    }
+  } catch {
+  }
+  return { balance: null, ccy };
+}
+var KNOWN_UNDERLYINGS = /^(BTC|ETH|TRX|EOS|SOL|IOTA|KISHU|SUSHI|BTG|XTZ|SOLVU)/i;
+function extractUnderlying(seriesId) {
+  const m = seriesId.match(KNOWN_UNDERLYINGS);
+  return m ? m[1].toUpperCase() : null;
+}
+function resolveOutcome(value) {
+  const map = {
+    up: "yes",
+    yes: "yes",
+    down: "no",
+    no: "no"
+  };
+  const resolved = map[value.toLowerCase()];
+  if (!resolved) {
+    throw new Error(
+      `Invalid outcome "${value}". Use: UP or YES for Up/Yes, DOWN or NO for Down/No.`
+    );
+  }
+  return resolved;
+}
+function filterBrowseCandidates(allSeries, underlyingFilter) {
+  const isHumanReadable = (id) => /^(BTC|ETH|TRX|EOS|SOL|IOTA|KISHU|SUSHI|BTG|XTZ|SOLVU)-/.test(id);
+  const seen = /* @__PURE__ */ new Set();
+  const candidates = [];
+  for (const s of allSeries) {
+    const settlement = s["settlement"];
+    const method = String(settlement?.["method"] ?? "");
+    const uly = String(settlement?.["underlying"] ?? "");
+    if (underlyingFilter && !uly.startsWith(underlyingFilter)) continue;
+    const key = `${method}:${uly}`;
+    if (!seen.has(key) && isHumanReadable(String(s["seriesId"] ?? ""))) {
+      seen.add(key);
+      candidates.push(s);
+    }
+  }
+  return candidates;
+}
+function isActiveMarket(m, isUpDown, now) {
+  if (!isUpDown && (!m["floorStrike"] || m["floorStrike"] === "")) return false;
+  const expMs = Number(m["expTime"] ?? 0);
+  return expMs <= 0 || expMs > now;
+}
+function toContractSummary(m) {
+  const converted = convertTimestamps(m);
+  const id = String(m["instId"] ?? "");
+  return {
+    instId: id,
+    displayTitle: formatDisplayTitle(id),
+    expTime: converted["expTime"],
+    floorStrike: m["floorStrike"],
+    px: m["px"],
+    outcome: OUTCOME_LABELS[String(m["outcome"] ?? "")] ?? m["outcome"]
+  };
+}
+async function fetchActiveContractsForSeries(client, s) {
+  const seriesId = String(s["seriesId"] ?? "");
+  const settlement = s["settlement"];
+  const method = String(settlement?.["method"] ?? "");
+  const isUpDown = method === "price_up_down";
+  try {
+    const r = await client.privateGet(
+      "/api/v5/public/event-contract/markets",
+      compactObject({ seriesId, state: "live" }),
+      privateRateLimit("event_browse", 20)
+    );
+    const normalized = normalizeResponse(r);
+    const markets = Array.isArray(normalized["data"]) ? normalized["data"] : [];
+    const now = Date.now();
+    const active = markets.filter((m) => isActiveMarket(m, isUpDown, now)).map(toContractSummary);
+    if (active.length === 0) return null;
+    return {
+      seriesId,
+      method: String(settlement?.["method"] ?? ""),
+      underlying: String(settlement?.["underlying"] ?? ""),
+      freq: String(s["freq"] ?? ""),
+      contracts: active
+    };
+  } catch {
+    return null;
+  }
+}
+function resolveUnderlyingFromSeriesResp(seriesResp) {
+  if (!seriesResp) return null;
+  const sResp = seriesResp;
+  const sData = Array.isArray(sResp["data"]) ? sResp["data"] : [];
+  if (sData.length > 0) {
+    const settlement = sData[0]["settlement"];
+    return String(settlement?.["underlying"] ?? "") || null;
+  }
+  return null;
+}
+function translateAndSortMarkets(rawData, limit) {
+  const sorted = [...rawData].sort((a, b) => {
+    const tA = Number(a["expTime"] ?? 0);
+    const tB = Number(b["expTime"] ?? 0);
+    return tA - tB;
+  });
+  const sliced = limit && limit > 0 ? sorted.slice(0, limit) : sorted;
+  return sliced.map((item) => {
+    const converted = convertTimestamps(item);
+    if (typeof converted["outcome"] === "string") {
+      converted["outcome"] = OUTCOME_LABELS[converted["outcome"]] ?? converted["outcome"];
+    }
+    converted["displayTitle"] = formatDisplayTitle(String(item["instId"] ?? ""));
+    return converted;
+  });
+}
+function enrichFill(item) {
+  const subType = String(item["subType"] ?? "");
+  const isSettle = subType === "414" || subType === "415";
+  const enriched = {
+    ...item,
+    displayTitle: formatDisplayTitle(String(item["instId"] ?? "")),
+    outcome: OUTCOME_LABELS[String(item["outcome"] ?? "")] ?? item["outcome"],
+    type: isSettle ? "settlement" : "fill"
+  };
+  if (isSettle) {
+    const fillPnl = parseFloat(String(item["fillPnl"] ?? "NaN"));
+    const isWin = subType === "414";
+    enriched["settlementResult"] = isWin ? "win" : "loss";
+    enriched["pnl"] = isNaN(fillPnl) ? void 0 : fillPnl;
+  }
+  return enriched;
+}
+async function fetchIdxPx(client, underlying) {
+  try {
+    const r = await client.publicGet(
+      "/api/v5/market/index-tickers",
+      { instId: underlying },
+      publicRateLimit("fetchIdxPx", 20)
+    );
+    const data = r["data"];
+    if (Array.isArray(data) && data.length > 0) {
+      return String(data[0]["idxPx"] ?? "") || null;
+    }
+  } catch {
+  }
+  return null;
+}
+function handlePlaceOrderError(base, rawArgs, endpoint) {
+  if (!Array.isArray(base["data"])) return;
+  const item = base["data"][0];
+  const sCode = item && String(item["sCode"] ?? "");
+  if (!sCode || sCode === "0") return;
+  const sMsg = String(item["sMsg"] ?? "Order failed");
+  if (sCode === "51001") {
+    const instId = requireString(asRecord(rawArgs), "instId");
+    const seriesId = extractSeriesId(instId);
+    const expiryMs = inferExpiryMsFromInstId(instId);
+    const isExpired = expiryMs !== null && expiryMs < Date.now();
+    const reason = isExpired ? `The contract (${instId}) has expired.` : `The contract (${instId}) was not found \u2014 it may not exist or has not started yet.`;
+    throw new OkxApiError(
+      `${reason} Ask the user if they'd like to place the same order on the next session. If yes, call event_get_markets with seriesId=${seriesId} and state=live to find available contracts.`,
+      { code: sCode, endpoint }
+    );
+  }
+  throw new OkxApiError(`[${sCode}] ${sMsg}`, { code: sCode, endpoint });
+}
+var OUTCOME_SCHEMA = {
+  type: "string",
+  enum: ["UP", "YES", "DOWN", "NO"],
+  description: `Which outcome to trade.
+UP/DOWN direction contracts: UP (price rises during the period) or DOWN (price falls).
+YES/NO price-target or touch contracts: YES (condition met) or NO (condition not met).
+Check the series type from event_get_series to determine which applies.
+NOTE: px is the event contract price (0.01\u20130.99), NOT the underlying asset price. It reflects market-implied probability when actively trading.`
+};
+function registerEventContractTools() {
+  return [
+    // -----------------------------------------------------------------------
+    // Read-only — browse (user-facing) + series / events / markets (internal)
+    // -----------------------------------------------------------------------
+    {
+      name: "event_browse",
+      module: "event",
+      description: "Browse currently active (in-progress) event contracts. Call when user asks what event contracts are available to trade. Internally fetches series and live markets in parallel, returns only in-progress contracts (floorStrike set). If a live quote field px is present, it is the event contract price (0.01\u20130.99), not the underlying asset price; it reflects the market-implied probability when actively trading. Grouped by settlement type and underlying.",
+      isWrite: false,
+      inputSchema: {
+        type: "object",
+        properties: {
+          underlying: {
+            type: "string",
+            description: "Filter by underlying asset, e.g. BTC-USD, ETH-USD. Omit for all."
+          }
+        }
+      },
+      handler: async (rawArgs, context) => {
+        const args = asRecord(rawArgs);
+        const underlyingFilter = readString(args, "underlying");
+        const seriesResp = await context.client.privateGet(
+          "/api/v5/public/event-contract/series",
+          compactObject({}),
+          privateRateLimit("event_browse", 10)
+        );
+        const normalizedSeries = normalizeResponse(seriesResp);
+        const allSeries = Array.isArray(normalizedSeries["data"]) ? normalizedSeries["data"] : [];
+        const candidates = filterBrowseCandidates(allSeries, underlyingFilter);
+        const marketResults = await Promise.all(
+          candidates.map((s) => fetchActiveContractsForSeries(context.client, s))
+        );
+        const results = marketResults.filter(Boolean);
+        return {
+          data: results,
+          total: results.reduce((n, r) => n + (r?.contracts?.length ?? 0), 0)
+        };
+      }
+    },
+    {
+      name: "event_get_series",
+      module: "event",
+      description: "List event contract series. Returns all available series with settlement type and underlying. Use event_browse to see currently active contracts.",
+      isWrite: false,
+      inputSchema: {
+        type: "object",
+        properties: {
+          seriesId: {
+            type: "string",
+            description: "Filter by series ID, e.g. BTC-ABOVE-DAILY. Omit for all."
+          }
+        }
+      },
+      handler: async (rawArgs, context) => {
+        const args = asRecord(rawArgs);
+        const response = await context.client.privateGet(
+          "/api/v5/public/event-contract/series",
+          compactObject({ seriesId: readString(args, "seriesId") }),
+          privateRateLimit("event_get_series", 20)
+        );
+        return normalizeResponse(response);
+      }
+    },
+    {
+      name: "event_get_events",
+      module: "event",
+      description: "List expiry periods within a series. state: preopen|live|settling|expired. expTime is pre-formatted UTC+8.",
+      isWrite: false,
+      inputSchema: {
+        type: "object",
+        properties: {
+          seriesId: {
+            type: "string",
+            description: "Series ID, e.g. BTC-ABOVE-DAILY (required)"
+          },
+          eventId: {
+            type: "string",
+            description: "Filter by event ID, e.g. BTC-ABOVE-DAILY-260224-1600"
+          },
+          state: {
+            type: "string",
+            enum: ["preopen", "live", "settling", "expired"],
+            description: "preopen=markets not yet trading; live=active; settling=awaiting settlement; expired=done"
+          },
+          limit: {
+            type: "number",
+            description: "Max results (default 100, max 100)"
+          },
+          before: {
+            type: "string",
+            description: "Pagination: return records newer than this expTime"
+          },
+          after: {
+            type: "string",
+            description: "Pagination: return records older than this expTime"
+          }
+        },
+        required: ["seriesId"]
+      },
+      handler: async (rawArgs, context) => {
+        const args = asRecord(rawArgs);
+        const response = await context.client.privateGet(
+          "/api/v5/public/event-contract/events",
+          compactObject({
+            seriesId: requireString(args, "seriesId"),
+            eventId: readString(args, "eventId"),
+            state: readString(args, "state"),
+            limit: readNumber(args, "limit"),
+            before: readString(args, "before"),
+            after: readString(args, "after")
+          }),
+          privateRateLimit("event_get_events", 20)
+        );
+        const base = normalizeResponse(response);
+        const data = Array.isArray(base["data"]) ? base["data"].map(convertTimestamps) : base["data"];
+        return { ...base, data };
+      }
+    },
+    {
+      name: "event_get_markets",
+      module: "event",
+      description: "List tradeable contracts within a series. state=live for active contracts, state=expired for settlement results. floorStrike=strike price; px (when present) is the event contract price (0.01\u20130.99), not the underlying asset price \u2014 reflects the market-implied probability when actively trading; outcome pre-translated (pending/YES/NO/UP/DOWN); timestamps UTC+8.",
+      isWrite: false,
+      inputSchema: {
+        type: "object",
+        properties: {
+          seriesId: {
+            type: "string",
+            description: "Series ID, e.g. BTC-ABOVE-DAILY (required)"
+          },
+          eventId: {
+            type: "string",
+            description: "Filter by event ID, e.g. BTC-ABOVE-DAILY-260224-1600"
+          },
+          instId: {
+            type: "string",
+            description: "Filter by instrument ID"
+          },
+          state: {
+            type: "string",
+            enum: ["preopen", "live", "settling", "expired"],
+            description: "preopen=not yet trading; live=active; settling=awaiting settlement; expired=settled"
+          },
+          limit: {
+            type: "number",
+            description: "Max results (default 100, max 100)"
+          },
+          before: {
+            type: "string",
+            description: "Pagination: return records newer than this expTime"
+          },
+          after: {
+            type: "string",
+            description: "Pagination: return records older than this expTime"
+          }
+        },
+        required: ["seriesId"]
+      },
+      handler: async (rawArgs, context) => {
+        const args = asRecord(rawArgs);
+        const seriesId = requireString(args, "seriesId");
+        const knownUnderlying = extractUnderlying(seriesId);
+        const [marketsResp, seriesResp, idxPxFromKnown] = await Promise.all([
+          context.client.privateGet(
+            "/api/v5/public/event-contract/markets",
+            compactObject({
+              seriesId,
+              eventId: readString(args, "eventId"),
+              instId: readString(args, "instId"),
+              state: readString(args, "state"),
+              before: readString(args, "before"),
+              after: readString(args, "after")
+            }),
+            privateRateLimit("event_get_markets", 20)
+          ),
+          knownUnderlying ? Promise.resolve(null) : context.client.privateGet(
+            "/api/v5/public/event-contract/series",
+            compactObject({ seriesId }),
+            privateRateLimit("event_get_series", 20)
+          ),
+          knownUnderlying ? fetchIdxPx(context.client, knownUnderlying + "-USDT") : Promise.resolve(null)
+        ]);
+        let underlying = knownUnderlying ? knownUnderlying + "-USDT" : null;
+        if (!underlying) {
+          underlying = resolveUnderlyingFromSeriesResp(seriesResp);
+        }
+        const idxPx = idxPxFromKnown ?? (underlying && !knownUnderlying ? await fetchIdxPx(context.client, underlying) : null);
+        const base = normalizeResponse(marketsResp);
+        const limit = readNumber(args, "limit");
+        const rawData = Array.isArray(base["data"]) ? base["data"] : [];
+        const translated = translateAndSortMarkets(rawData, limit);
+        return {
+          ...base,
+          data: translated,
+          currentIdxPx: idxPx,
+          underlying
+        };
+      }
+    },
+    {
+      name: "event_get_orders",
+      module: "event",
+      description: "Query event contract orders. state=live for open orders; omit for history. outcome pre-translated (YES/NO/UP/DOWN).",
+      isWrite: false,
+      inputSchema: {
+        type: "object",
+        properties: {
+          instId: {
+            type: "string",
+            description: "Event contract instrument ID"
+          },
+          state: {
+            type: "string",
+            description: "live=pending orders; omit for history"
+          },
+          limit: {
+            type: "number",
+            description: "Max results (default 20)"
+          }
+        }
+      },
+      handler: async (rawArgs, context) => {
+        const args = asRecord(rawArgs);
+        const state = readString(args, "state");
+        const isPending = state === "live";
+        const endpoint = isPending ? "/api/v5/trade/orders-pending" : "/api/v5/trade/orders-history";
+        const response = await context.client.privateGet(
+          endpoint,
+          compactObject({
+            instType: "EVENTS",
+            instId: readString(args, "instId"),
+            limit: readNumber(args, "limit")
+          }),
+          privateRateLimit("event_get_orders", 20)
+        );
+        const base = normalizeResponse(response);
+        const data = Array.isArray(base["data"]) ? base["data"].map((item) => ({
+          ...item,
+          displayTitle: formatDisplayTitle(String(item["instId"] ?? "")),
+          outcome: OUTCOME_LABELS[String(item["outcome"] ?? "")] ?? item["outcome"],
+          state: String(item["state"] ?? ""),
+          stateLabel: mapOrderState(String(item["state"] ?? ""))
+        })) : base["data"];
+        return { ...base, data };
+      }
+    },
+    {
+      name: "event_get_fills",
+      module: "event",
+      description: "Get event contract fill history. outcome pre-translated (YES/NO/UP/DOWN). Each record includes a 'type' field: 'fill' (subType 410, opening trade) or 'settlement' (subType 414 win / subType 415 loss, contract expiry payout). Settlement records include 'settlementResult' (win/loss) and 'pnl' fields \u2014 no separate market lookup needed to determine outcome.",
+      isWrite: false,
+      inputSchema: {
+        type: "object",
+        properties: {
+          instId: {
+            type: "string",
+            description: "Event contract instrument ID"
+          },
+          limit: {
+            type: "number",
+            description: "Max results (default 20)"
+          }
+        }
+      },
+      handler: async (rawArgs, context) => {
+        const args = asRecord(rawArgs);
+        const response = await context.client.privateGet(
+          "/api/v5/trade/fills",
+          compactObject({
+            instType: "EVENTS",
+            instId: readString(args, "instId"),
+            limit: readNumber(args, "limit")
+          }),
+          privateRateLimit("event_get_fills", 20)
+        );
+        const base = normalizeResponse(response);
+        const data = Array.isArray(base["data"]) ? base["data"].map(enrichFill) : base["data"];
+        return { ...base, data };
+      }
+    },
+    // -----------------------------------------------------------------------
+    // Private — write
+    // -----------------------------------------------------------------------
+    {
+      name: "event_place_order",
+      module: "event",
+      description: `Place an event contract order. [CAUTION] Places a real order.
+- outcome: UP/YES (bet price goes up/condition met) or DOWN/NO (bet price goes down/condition not met)
+- For limit orders: px is the event contract price (0.01\u20130.99), NOT the underlying asset price. It reflects market-implied probability when actively trading
+- tdMode is always isolated; speedBump is auto-set per exchange requirement \u2014 do not pass either`,
+      isWrite: true,
+      inputSchema: {
+        type: "object",
+        properties: {
+          instId: {
+            type: "string",
+            description: "Event contract instrument ID, e.g. BTC-ABOVE-DAILY-260224-1600-120000"
+          },
+          side: {
+            type: "string",
+            enum: ["buy", "sell"],
+            description: "buy=open position, sell=close position"
+          },
+          outcome: OUTCOME_SCHEMA,
+          ordType: {
+            type: "string",
+            enum: ["market", "limit", "post_only"],
+            description: "Order type (default market)"
+          },
+          sz: {
+            type: "string",
+            description: "For limit/post_only: number of contracts. For market: quote currency amount (server converts to contracts using best available price; actual fill count may differ)."
+          },
+          px: {
+            type: "string",
+            description: "Event contract price (0.01\u20130.99). Required when ordType=limit. Do NOT use for market orders."
+          }
+        },
+        required: ["instId", "side", "outcome", "sz"]
+      },
+      handler: async (rawArgs, context) => {
+        const args = asRecord(rawArgs);
+        const ordType = readString(args, "ordType") ?? "market";
+        const speedBump = ordType !== "post_only" ? "1" : void 0;
+        const instId = requireString(args, "instId");
+        const response = await context.client.privatePost(
+          "/api/v5/trade/order",
+          compactObject({
+            instId,
+            tdMode: "isolated",
+            side: requireString(args, "side"),
+            outcome: resolveOutcome(requireString(args, "outcome")),
+            ordType,
+            sz: requireString(args, "sz"),
+            px: readString(args, "px"),
+            speedBump,
+            tag: context.config.sourceTag
+          }),
+          privateRateLimit("event_place_order", 60)
+        );
+        const base = normalizeResponse(response);
+        handlePlaceOrderError(base, asRecord(rawArgs), response.endpoint);
+        const data = Array.isArray(base["data"]) ? base["data"].map(({ tag: _t, ...rest }) => rest) : base["data"];
+        const placeSeriesId = extractSeriesId(instId);
+        const placeUnderlying = extractUnderlying(placeSeriesId);
+        const placeCcy = extractQuoteCcy(placeUnderlying ? placeUnderlying + "-USDT" : null);
+        const balResult = await fetchAvailableBalance(context.client, placeCcy);
+        const result = { ...base, data };
+        if (balResult.balance) {
+          result["availableBalance"] = balResult.balance;
+          result["availableBalanceCcy"] = balResult.ccy;
+        }
+        if (ordType === "market") {
+          result["orderNote"] = "Market order: sz is a quote currency amount. The exchange converts it to contracts based on best available price.";
+        }
+        return result;
+      }
+    },
+    {
+      name: "event_amend_order",
+      module: "event",
+      description: "Amend a pending event contract order (change price or size). [CAUTION] Modifies a real order. Only limit/post_only orders can be amended.",
+      isWrite: true,
+      inputSchema: {
+        type: "object",
+        properties: {
+          instId: { type: "string", description: "Event contract instrument ID" },
+          ordId: { type: "string", description: "Order ID to amend" },
+          newPx: { type: "string", description: "New event contract price (0.01\u20130.99). Omit to keep current." },
+          newSz: { type: "string", description: "New size in contracts (omit to keep current)" }
+        },
+        required: ["instId", "ordId"]
+      },
+      handler: async (rawArgs, context) => {
+        const args = asRecord(rawArgs);
+        const response = await context.client.privatePost(
+          "/api/v5/trade/amend-order",
+          compactObject({
+            instId: requireString(args, "instId"),
+            ordId: requireString(args, "ordId"),
+            newPx: readString(args, "newPx"),
+            newSz: readString(args, "newSz"),
+            speedBump: "1"
+          }),
+          privateRateLimit("event_amend_order", 60)
+        );
+        return normalizeWrite3(response);
+      }
+    },
+    {
+      name: "event_cancel_order",
+      module: "event",
+      description: "Cancel a pending event contract order. [CAUTION] Cancels a real order. instId must be the full event contract instrument ID (e.g. BTC-ABOVE-DAILY-260224-1600-69700), NOT a spot trading pair.",
+      isWrite: true,
+      inputSchema: {
+        type: "object",
+        properties: {
+          instId: {
+            type: "string",
+            description: "Event contract instrument ID"
+          },
+          ordId: {
+            type: "string",
+            description: "Order ID to cancel"
+          }
+        },
+        required: ["instId", "ordId"]
+      },
+      handler: async (rawArgs, context) => {
+        const args = asRecord(rawArgs);
+        const instId = requireString(args, "instId");
+        const response = await context.client.privatePost(
+          "/api/v5/trade/cancel-order",
+          { instId, ordId: requireString(args, "ordId") },
+          privateRateLimit("event_cancel_order", 60)
+        );
+        if (Array.isArray(response.data) && response.data.length > 0) {
+          const item = response.data[0];
+          const sCode = item && String(item["sCode"] ?? "");
+          if (sCode === "51001") {
+            const expiryMs = inferExpiryMsFromInstId(instId);
+            const isExpired = expiryMs !== null && expiryMs < Date.now();
+            const reason = isExpired ? `The contract (${instId}) has already expired \u2014 the order was auto-cancelled at settlement. Check event_get_fills to confirm the outcome.` : `Instrument (${instId}) not found. Verify the instId with event_get_markets before retrying.`;
+            throw new OkxApiError(reason, { code: sCode, endpoint: response.endpoint });
+          }
+        }
+        return normalizeWrite3(response);
+      }
+    }
+  ];
+}
 function buildContractTradeTools(cfg) {
   const { prefix, module, label, instTypes, instIdExample } = cfg;
   const [defaultType, otherType] = instTypes;
@@ -7455,6 +8219,7 @@ function allToolSpecs() {
     ...registerOptionAlgoTools(),
     ...registerAlgoTradeTools(),
     ...registerAccountTools(),
+    ...registerEventContractTools(),
     ...registerBotTools(),
     ...registerAllEarnTools(),
     ...registerAuditTools(),
@@ -7901,7 +8666,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 ? "6d4d559" : "dev";
+var GIT_HASH = true ? "765bfa2" : "dev";
 
 // src/server.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";