get_unusual_options_activity

Instructions

Implementation Reference

• src/tools/optionsFlow.ts:135-170 (handler)

  Handler function that fetches unusual options activity from the API and applies client-side filtering by symbol, side, min vol/oi ratio, min premium, and max days to expiration.

  export async function handleGetUnusualOptionsActivity(
    ctx: McpContext,
    rawArgs: unknown
  ): Promise<unknown> {
    const args = GetUnusualOptionsActivityInputSchema.parse(rawArgs);
    const limit = args.limit ?? 300;
    const side = args.side ?? "both";
    const minVolOi = args.min_vol_oi ?? 1.5;
    const minPremium = args.min_premium_usd ?? 25000;
  
    const raw = await ctx.cache.wrap(`uoa:raw:${limit}`, 120_000, () =>
      ctx.apiClient.get<{ data?: UnusualContract[] }>(`/options-flow/unusual`, { limit })
    );
  
    // Client-side filter
    const toNum = (v: unknown) => {
      if (typeof v === "number") return v;
      if (typeof v === "string") return Number(v.replace(/,/g, "")) || 0;
      return 0;
    };
    const contracts = (raw.data || []).filter((r: UnusualContract) => {
      if (args.symbol && (r.symbol || "").toUpperCase() !== args.symbol.toUpperCase()) return false;
      if (side === "call" && r.symbol_type !== "Call") return false;
      if (side === "put" && r.symbol_type !== "Put") return false;
      if (toNum(r.volume_oi_ratio) < minVolOi) return false;
      const premium = toNum(r.last_price) * toNum(r.volume) * 100;
      if (premium < minPremium) return false;
      if (args.max_dte != null && (r.days_to_expiration || 0) > args.max_dte) return false;
      return true;
    });
  
    return {
      count: contracts.length,
      contracts,
    };
  }

• src/tools/optionsFlow.ts:40-47 (schema)

  Zod schema defining the input parameters: symbol (optional), side (call/put/both), min_vol_oi, min_premium_usd, max_dte, and limit.

  export const GetUnusualOptionsActivityInputSchema = z.object({
    symbol: z.string().regex(symbolRegex).optional().describe("Filter to one symbol"),
    side: z.enum(["call", "put", "both"]).default("both").optional(),
    min_vol_oi: z.number().min(0).default(1.5).optional(),
    min_premium_usd: z.number().min(0).default(25000).optional(),
    max_dte: z.number().int().min(0).optional(),
    limit: z.number().int().min(1).max(1000).default(300).optional(),
  });

• src/tools/optionsFlow.ts:72-80 (registration)

  Tool registration in the optionsFlowTools array with name 'get_unusual_options_activity', description, input schema, and read-only annotations.

      name: "get_unusual_options_activity",
      description:
        "Return individual options contracts flagged as unusual (Vol/OI > 1.5). Each row is one contract, not one stock. Use when the user wants contract-level detail. Filter by symbol, side (call/put/both), minimum vol/oi, minimum premium, or max days to expiration. For aggregated stock-level flow use get_options_flow_overview instead. Returns { date, count, contracts: [...] }.",
      inputSchema: z.toJSONSchema(GetUnusualOptionsActivityInputSchema) as Tool["inputSchema"],
      annotations: READ_ONLY_ANNOTATIONS,
    },
  ];
  
  export async function handleGetOptionsFlowOverview(

• src/tools/index.ts:80-89 (registration)

  Handler mapping in src/tools/index.ts that wires the tool name 'get_unusual_options_activity' to the handleGetUnusualOptionsActivity function.

    get_unusual_options_activity: (ctx, args) => handleGetUnusualOptionsActivity(ctx, args),
    get_stock_info: (ctx, args) => handleGetStockInfo(ctx, args),
    get_candles: (ctx, args) => handleGetCandles(ctx, args),
    get_stock_report: (ctx, args) => handleGetStockReport(ctx, args),
    search_setups: (ctx, args) => handleSearchSetups(ctx, args),
    get_market_momentum: (ctx, args) => handleGetMarketMomentum(ctx, args),
    get_trends: (ctx, args) => handleGetTrends(ctx, args),
    get_trend_connections: (ctx, args) => handleGetTrendConnections(ctx, args),
    explain_concept: (ctx, args) => handleExplainConcept(ctx, args),
  };

• src/tools/optionsFlow.ts:125-133 (helper)

  TypeScript interface representing the shape of an unusual options contract returned by the API.

  interface UnusualContract {
    symbol?: string;
    symbol_type?: string;
    volume?: string | number;
    open_interest?: string | number;
    volume_oi_ratio?: string | number;
    last_price?: string | number;
    days_to_expiration?: number;
  }