opencandle 0.4.0 → 0.6.0

package/src/tools/market/search-ticker.ts

@@ -1,46 +1,64 @@
-import { Type } from "@sinclair/typebox";
 import type { AgentTool } from "@earendil-works/pi-agent-core";
-import { httpGet } from "../../infra/http-client.js";
+import { Type } from "@sinclair/typebox";
+import { httpGet, httpPost } from "../../infra/http-client.js";
+import { rateLimiter } from "../../infra/rate-limiter.js";
 
 const params = Type.Object({
   query: Type.String({
-    description: "Search query — company name, ticker symbol, or crypto name (e.g. 'apple', 'AAPL', 'ethereum', 'bitcoin')",
+    description:
+      "Search query — company name, ticker symbol, or crypto name (e.g. 'apple', 'AAPL', 'ethereum', 'bitcoin')",
   }),
 });
 
 interface YahooSearchResponse {
-  quotes: Array<{
-    symbol: string;
-    shortname?: string;
-    longname?: string;
-    quoteType: string;
-    exchange: string;
-    score: number;
+  quotes?: YahooSearchQuote[];
+}
+
+interface YahooSearchQuote {
+  symbol: string;
+  shortname?: string;
+  longname?: string;
+  quoteType: string;
+  exchange: string;
+  score: number;
+}
+
+interface TradingViewSearchResponse {
+  fields?: string[];
+  symbols?: Array<{
+    s: string;
+    f: unknown[];
   }>;
 }
 
+const FALLBACK_SEARCH_MAX_RETRY_AFTER_MS = 1_000;
+
 export const searchTickerTool: AgentTool<typeof params> = {
   name: "search_ticker",
   label: "Search Ticker",
   description:
     "Search for any ticker symbol — stocks, crypto, ETFs, indices, forex. Returns matching symbols with names and exchange info. Use this when you don't know the exact ticker for an asset.",
   parameters: params,
-  async execute(toolCallId, args) {
-    const url = `https://query1.finance.yahoo.com/v1/finance/search?q=${encodeURIComponent(args.query)}&quotesCount=10&newsCount=0`;
-    const data = await httpGet<YahooSearchResponse>(url, {
-      headers: { "User-Agent": "OpenCandle/1.0" },
-    });
+  async execute(_toolCallId, args) {
+    const yahoo = await searchYahoo(args.query);
+    const fallback = yahoo.quotes.length > 0 ? { quotes: [] } : await searchTradingView(args.query);
+    const quotes = yahoo.quotes.length > 0 ? yahoo.quotes : fallback.quotes;
 
-    const quotes = data.quotes ?? [];
     if (quotes.length === 0) {
+      const fallbackError = "error" in fallback ? fallback.error : undefined;
       return {
-        content: [{ type: "text", text: `No results found for "${args.query}"` }],
+        content: [
+          {
+            type: "text",
+            text: formatNoResultsText(args.query, yahoo.error, fallbackError),
+          },
+        ],
         details: quotes,
       };
     }
 
     const lines = [
-      `**Search results for "${args.query}"** — ${quotes.length} matches`,
+      `**Search results for "${args.query}"** — ${quotes.length} matches${yahoo.quotes.length === 0 ? " (TradingView fallback)" : ""}`,
       "",
       ...quotes.map(
         (q) =>
@@ -51,3 +69,186 @@ export const searchTickerTool: AgentTool<typeof params> = {
     return { content: [{ type: "text", text: lines.join("\n") }], details: quotes };
   },
 };
+
+function formatNoResultsText(
+  query: string,
+  yahooError?: string,
+  tradingViewError?: string,
+): string {
+  if (yahooError && tradingViewError) {
+    return `No results found for "${query}". Yahoo search was unavailable (${yahooError}), and the TradingView fallback was unavailable (${tradingViewError}).`;
+  }
+  if (yahooError) {
+    return `No results found for "${query}". Yahoo search was unavailable (${yahooError}), and the TradingView fallback found no equity matches.`;
+  }
+  if (tradingViewError) {
+    return `No results found for "${query}". TradingView fallback was unavailable (${tradingViewError}).`;
+  }
+  return `No results found for "${query}"`;
+}
+
+async function searchYahoo(query: string): Promise<{ quotes: YahooSearchQuote[]; error?: string }> {
+  const url = `https://query1.finance.yahoo.com/v1/finance/search?q=${encodeURIComponent(query)}&quotesCount=10&newsCount=0`;
+  try {
+    await rateLimiter.acquire("yahoo");
+    const data = await httpGet<YahooSearchResponse>(url, {
+      headers: { "User-Agent": "OpenCandle/1.0" },
+      maxRetryAfterMs: FALLBACK_SEARCH_MAX_RETRY_AFTER_MS,
+    });
+    return { quotes: data.quotes ?? [] };
+  } catch (error) {
+    return {
+      quotes: [],
+      error: error instanceof Error ? error.message : "unknown_error",
+    };
+  }
+}
+
+async function searchTradingView(
+  query: string,
+): Promise<{ quotes: YahooSearchQuote[]; error?: string }> {
+  const normalized = query.trim();
+  if (!normalized) return { quotes: [] };
+
+  try {
+    const exactTicker = normalizeTickerQuery(normalized);
+    if (exactTicker) {
+      const exact = await fetchTradingViewSearch(
+        buildTradingViewSearchBody({
+          query: normalized,
+          ticker: exactTicker,
+          mode: "ticker",
+        }),
+      );
+      const exactQuotes = decodeTradingViewSearch(exact, normalized).slice(0, 10);
+      if (exactQuotes.length > 0) return { quotes: exactQuotes };
+    }
+
+    const matched = await fetchTradingViewSearch(
+      buildTradingViewSearchBody({
+        query: normalized,
+        mode: "description",
+      }),
+    );
+    return { quotes: decodeTradingViewSearch(matched, normalized).slice(0, 10) };
+  } catch (error) {
+    return {
+      quotes: [],
+      error: error instanceof Error ? error.message : "unknown_error",
+    };
+  }
+}
+
+async function fetchTradingViewSearch(
+  body: ReturnType<typeof buildTradingViewSearchBody>,
+): Promise<TradingViewSearchResponse> {
+  await rateLimiter.acquire("tradingview");
+  return await httpPost<TradingViewSearchResponse>(
+    "https://scanner.tradingview.com/america/scan2?label-product=screener-stock",
+    body,
+    {
+      headers: {
+        Origin: "https://www.tradingview.com",
+        Referer: "https://www.tradingview.com/",
+        "User-Agent":
+          "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
+      },
+    },
+  );
+}
+
+function buildTradingViewSearchBody(options: {
+  query: string;
+  mode: "ticker" | "description";
+  ticker?: string;
+}) {
+  const columns = ["name", "description", "exchange", "type", "typespecs"] as const;
+  const filter =
+    options.mode === "ticker" && options.ticker
+      ? [
+          { left: "name", operation: "equal", right: options.ticker },
+          { left: "is_primary", operation: "equal", right: true },
+          { left: "type", operation: "in_range", right: ["stock", "fund", "dr"] },
+        ]
+      : [
+          { left: "description", operation: "match", right: options.query },
+          { left: "type", operation: "in_range", right: ["stock", "fund", "dr"] },
+        ];
+
+  return {
+    markets: ["america"],
+    columns,
+    filter,
+    sort: { sortBy: "market_cap_basic", sortOrder: "desc" },
+    range: [0, 10],
+    options: { lang: "en" },
+  };
+}
+
+function decodeTradingViewSearch(
+  response: TradingViewSearchResponse,
+  query: string,
+): YahooSearchQuote[] {
+  const fields = response.fields ?? [];
+  const queryTicker = normalizeTickerQuery(query);
+  return (response.symbols ?? [])
+    .map((row, index) => {
+      const values = Object.fromEntries(
+        fields.map((field, fieldIndex) => [field, row.f[fieldIndex]]),
+      );
+      const symbol = stringValue(values.name) ?? symbolFromTvSymbol(row.s);
+      const longname = stringValue(values.description);
+      const exchange = stringValue(values.exchange) ?? exchangeFromTvSymbol(row.s);
+      return {
+        symbol,
+        shortname: longname,
+        longname,
+        quoteType: quoteTypeFromTradingView(values.type, values.typespecs),
+        exchange,
+        score: scoreTradingViewResult({ symbol, exchange, index, queryTicker }),
+      };
+    })
+    .sort((a, b) => b.score - a.score || a.symbol.localeCompare(b.symbol));
+}
+
+function scoreTradingViewResult(opts: {
+  symbol: string;
+  exchange: string;
+  index: number;
+  queryTicker?: string;
+}): number {
+  let score = 50_000 - opts.index;
+  if (opts.queryTicker && opts.symbol.toUpperCase() === opts.queryTicker) score += 50_000;
+  const exchange = opts.exchange.toUpperCase();
+  if (exchange === "NASDAQ" || exchange === "NYSE") score += 1_000;
+  if (exchange === "AMEX") score += 500;
+  return score;
+}
+
+function quoteTypeFromTradingView(type: unknown, typespecs: unknown): string {
+  const normalizedType = stringValue(type)?.toLowerCase();
+  const normalizedSpecs = Array.isArray(typespecs)
+    ? typespecs.map((value) => String(value).toLowerCase())
+    : [];
+  if (normalizedType === "fund" && normalizedSpecs.includes("etf")) return "ETF";
+  if (normalizedType === "fund") return "MUTUALFUND";
+  if (normalizedType === "dr") return "EQUITY";
+  return "EQUITY";
+}
+
+function normalizeTickerQuery(query: string): string | undefined {
+  const normalized = query.trim().toUpperCase();
+  return /^[A-Z0-9][A-Z0-9.-]{0,9}$/.test(normalized) ? normalized : undefined;
+}
+
+function symbolFromTvSymbol(tvSymbol: string): string {
+  return tvSymbol.includes(":") ? tvSymbol.split(":").at(-1)! : tvSymbol;
+}
+
+function exchangeFromTvSymbol(tvSymbol: string): string {
+  return tvSymbol.includes(":") ? tvSymbol.split(":")[0] : "";
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}

package/src/tools/market/stock-history.ts

@@ -1,26 +1,46 @@
-import { Type } from "@sinclair/typebox";
 import type { AgentTool } from "@earendil-works/pi-agent-core";
-import { getHistory } from "../../providers/yahoo-finance.js";
+import { Type } from "@sinclair/typebox";
+import { getConfig } from "../../config.js";
 import { getDailyHistory } from "../../providers/alpha-vantage.js";
-import { wrapProvider } from "../../providers/wrap-provider.js";
 import { withFallback } from "../../providers/with-fallback.js";
-import { getConfig } from "../../config.js";
-import type { OHLCV } from "../../types/market.js";
+import { wrapProvider } from "../../providers/wrap-provider.js";
+import { getHistory } from "../../providers/yahoo-finance.js";
 import type { ProviderResult } from "../../runtime/evidence.js";
+import type { OHLCV } from "../../types/market.js";
 
 const DAILY_INTERVALS = new Set(["1d", "1wk", "1mo"]);
+const HISTORY_RANGES = [
+  "1d",
+  "5d",
+  "1mo",
+  "3mo",
+  "6mo",
+  "ytd",
+  "1y",
+  "2y",
+  "5y",
+  "10y",
+  "max",
+] as const;
+const HISTORY_INTERVALS = ["1m", "5m", "15m", "1h", "1d", "1wk", "1mo"] as const;
 
 const params = Type.Object({
   symbol: Type.String({ description: "Stock ticker symbol (e.g. AAPL, MSFT)" }),
   range: Type.Optional(
-    Type.String({
-      description: "Time range: 1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, max. Default: 6mo",
-    }),
+    Type.Union(
+      HISTORY_RANGES.map((range) => Type.Literal(range)),
+      {
+        description: "Time range: 1d, 5d, 1mo, 3mo, 6mo, ytd, 1y, 2y, 5y, 10y, max. Default: 6mo",
+      },
+    ),
   ),
   interval: Type.Optional(
-    Type.String({
-      description: "Data interval: 1m, 5m, 15m, 1h, 1d, 1wk, 1mo. Default: 1d",
-    }),
+    Type.Union(
+      HISTORY_INTERVALS.map((interval) => Type.Literal(interval)),
+      {
+        description: "Data interval: 1m, 5m, 15m, 1h, 1d, 1wk, 1mo. Default: 1d",
+      },
+    ),
   ),
 });
 
@@ -29,7 +49,7 @@ export const stockHistoryTool: AgentTool<typeof params, OHLCV[]> = {
   label: "Stock History",
   description: "Get historical OHLCV (open, high, low, close, volume) data for a stock",
   parameters: params,
-  async execute(toolCallId, args) {
+  async execute(_toolCallId, args) {
     const symbol = args.symbol.toUpperCase();
     const range = args.range ?? "6mo";
     const interval = args.interval ?? "1d";
@@ -53,7 +73,12 @@ export const stockHistoryTool: AgentTool<typeof params, OHLCV[]> = {
         ? ` No alternate source for ${interval} data.`
         : "";
       return {
-        content: [{ type: "text", text: `⚠ Stock history unavailable for ${symbol} (${result.reason}).${intradayNote}` }],
+        content: [
+          {
+            type: "text",
+            text: `⚠ Stock history unavailable for ${symbol} (${result.reason}).${intradayNote}`,
+          },
+        ],
         details: [],
       };
     }

package/src/tools/market/stock-quote.ts

@@ -1,9 +1,9 @@
-import { Type } from "@sinclair/typebox";
 import type { AgentTool } from "@earendil-works/pi-agent-core";
-import { getQuote } from "../../providers/yahoo-finance.js";
+import { Type } from "@sinclair/typebox";
+import { getConfig } from "../../config.js";
 import { getGlobalQuote } from "../../providers/alpha-vantage.js";
 import { withFallback } from "../../providers/with-fallback.js";
-import { getConfig } from "../../config.js";
+import { getQuote } from "../../providers/yahoo-finance.js";
 import type { StockQuote } from "../../types/market.js";
 
 const params = Type.Object({
@@ -16,7 +16,7 @@ export const stockQuoteTool: AgentTool<typeof params, StockQuote> = {
   description:
     "Get real-time stock price, volume, market cap, and 52-week range for a ticker symbol",
   parameters: params,
-  async execute(toolCallId, args) {
+  async execute(_toolCallId, args) {
     const symbol = args.symbol.toUpperCase();
     const apiKey = getConfig().alphaVantageApiKey;
 
@@ -30,16 +30,19 @@ export const stockQuoteTool: AgentTool<typeof params, StockQuote> = {
     const result = await withFallback(entries);
     if (result.status === "unavailable") {
       return {
-        content: [{ type: "text", text: `⚠ Stock quote unavailable for ${symbol} (${result.reason}).` }],
+        content: [
+          { type: "text", text: `⚠ Stock quote unavailable for ${symbol} (${result.reason}).` },
+        ],
         details: null as any,
       };
     }
     const quote = result.data;
     const sign = quote.changePercent >= 0 ? "+" : "";
 
-    const week52 = quote.week52High > 0 && quote.week52Low > 0
-      ? `$${quote.week52Low.toFixed(2)} - $${quote.week52High.toFixed(2)}`
-      : "N/A";
+    const week52 =
+      quote.week52High > 0 && quote.week52Low > 0
+        ? `$${quote.week52Low.toFixed(2)} - $${quote.week52High.toFixed(2)}`
+        : "N/A";
     const marketCapStr = quote.marketCap > 0 ? `$${formatLargeNumber(quote.marketCap)}` : "N/A";
 
     const text = [

package/src/tools/options/greeks.ts

@@ -2,10 +2,10 @@ import type { Greeks } from "../../types/options.js";
 
 interface GreeksInput {
   type: "call" | "put";
-  spot: number;       // underlying price
-  strike: number;     // strike price
-  timeYears: number;  // time to expiration in years
-  iv: number;         // implied volatility (e.g. 0.30 for 30%)
+  spot: number; // underlying price
+  strike: number; // strike price
+  timeYears: number; // time to expiration in years
+  iv: number; // implied volatility (e.g. 0.30 for 30%)
   riskFreeRate: number; // risk-free rate (e.g. 0.05 for 5%)
 }
 
@@ -47,7 +47,6 @@ export function computeGreeks(input: GreeksInput): Greeks {
       rho: (strike * timeYears * expRT * nd2) / 100, // per 1% change in rate
     };
   } else {
-    const nMinusD1 = cdf(-d1);
     const nMinusD2 = cdf(-d2);
     return {
       delta: nd1 - 1,
@@ -72,7 +71,7 @@ function cdf(x: number): number {
   const sign = x < 0 ? -1 : 1;
   const absX = Math.abs(x);
   const t = 1 / (1 + p * absX);
-  const y = 1 - ((((a5 * t + a4) * t + a3) * t + a2) * t + a1) * t * Math.exp(-absX * absX / 2);
+  const y = 1 - ((((a5 * t + a4) * t + a3) * t + a2) * t + a1) * t * Math.exp((-absX * absX) / 2);
   return 0.5 * (1 + sign * y);
 }
 

package/src/tools/options/option-chain.ts

@@ -1,21 +1,24 @@
-import { Type } from "@sinclair/typebox";
 import type { AgentTool } from "@earendil-works/pi-agent-core";
-import { getOptionsChain } from "../../providers/yahoo-finance.js";
+import { Type } from "@sinclair/typebox";
 import { wrapProvider } from "../../providers/wrap-provider.js";
-import type { OptionsChain, OptionContract } from "../../types/options.js";
+import { getOptionsChain } from "../../providers/yahoo-finance.js";
+import type { OptionContract, OptionsChain } from "../../types/options.js";
 
 const params = Type.Object({
   symbol: Type.String({ description: "Stock ticker symbol (e.g. AAPL, TSLA, SPY, MSFT)" }),
   expiration: Type.Optional(
     Type.String({
-      description:
-        "Expiration date as YYYY-MM-DD. If omitted, uses the nearest expiration.",
+      pattern: "^\\d{4}-\\d{2}-\\d{2}$",
+      description: "Expiration date as YYYY-MM-DD. If omitted, uses the nearest expiration.",
     }),
   ),
   type: Type.Optional(
-    Type.Union([Type.Literal("call"), Type.Literal("put"), Type.Literal("CALL"), Type.Literal("PUT")], {
-      description: "Filter by option type. Omit for both calls and puts.",
-    }),
+    Type.Union(
+      [Type.Literal("call"), Type.Literal("put"), Type.Literal("CALL"), Type.Literal("PUT")],
+      {
+        description: "Filter by option type. Omit for both calls and puts.",
+      },
+    ),
   ),
 });
 
@@ -25,17 +28,17 @@ export const optionChainTool: AgentTool<typeof params, OptionsChain> = {
   description:
     "Get the full options chain for a stock with strikes, bids, asks, volume, open interest, implied volatility, and computed Greeks (Delta, Gamma, Theta, Vega, Rho via Black-Scholes). No API key required.",
   parameters: params,
-  async execute(toolCallId, args) {
+  async execute(_toolCallId, args) {
     const symbol = args.symbol.toUpperCase();
     const normalizedType = args.type?.toLowerCase();
-    const expirationTs = args.expiration
-      ? Math.floor(new Date(args.expiration).getTime() / 1000)
-      : undefined;
+    const expirationTs = args.expiration ? parseExpiration(args.expiration) : undefined;
 
     const result = await wrapProvider("yahoo", () => getOptionsChain(symbol, expirationTs));
     if (result.status === "unavailable") {
       return {
-        content: [{ type: "text", text: `⚠ Options chain unavailable for ${symbol} (${result.reason}).` }],
+        content: [
+          { type: "text", text: `⚠ Options chain unavailable for ${symbol} (${result.reason}).` },
+        ],
         details: null as any,
       };
     }
@@ -44,6 +47,13 @@ export const optionChainTool: AgentTool<typeof params, OptionsChain> = {
     const lines: string[] = [
       `**${chain.symbol} Options Chain** — Expiry: ${chain.expirationDate}`,
       `Underlying: $${chain.underlyingPrice.toFixed(2)}`,
+      `Quote status: ${chain.quoteStatus.marketSession} / ${chain.quoteStatus.bidAskState}`,
+      "Option bid/ask and last prices are quoted per share; multiply by 100 for one standard contract premium.",
+      ...(chain.quoteStatus.warning
+        ? [
+            `⚠ ${chain.quoteStatus.warning} do not treat zero bid/ask as confirmed live illiquidity without broker verification; do not stop at the stale quote caveat. Disclose the gap, avoid naming tradable live premiums, and finish the strategy explanation with mechanics, assignment outcomes, labeled hypotheticals, and what live broker quotes would change.`,
+          ]
+        : []),
       `Available expirations: ${formatAvailableExpirations(chain.expirationDates)}`,
       "",
     ];
@@ -52,8 +62,12 @@ export const optionChainTool: AgentTool<typeof params, OptionsChain> = {
     const showPuts = !normalizedType || normalizedType === "put";
 
     if (showCalls && chain.calls.length > 0) {
-      lines.push(`**CALLS** (${chain.calls.length} contracts, volume: ${chain.totalCallVolume.toLocaleString()})`);
-      lines.push("Strike | Bid/Ask | Last | Vol | OI | IV | Delta | Theta");
+      lines.push(
+        `**CALLS** (${chain.calls.length} contracts, volume: ${chain.totalCallVolume.toLocaleString()})`,
+      );
+      lines.push(
+        "Strike | Bid/Ask (per share) | Last (per share) | Vol | OI | IV | Delta | Gamma | Theta | Vega | Rho",
+      );
       const topCalls = sortByVolume(chain.calls).slice(0, 10);
       for (const c of topCalls) {
         lines.push(formatContract(c));
@@ -62,8 +76,12 @@ export const optionChainTool: AgentTool<typeof params, OptionsChain> = {
     }
 
     if (showPuts && chain.puts.length > 0) {
-      lines.push(`**PUTS** (${chain.puts.length} contracts, volume: ${chain.totalPutVolume.toLocaleString()})`);
-      lines.push("Strike | Bid/Ask | Last | Vol | OI | IV | Delta | Theta");
+      lines.push(
+        `**PUTS** (${chain.puts.length} contracts, volume: ${chain.totalPutVolume.toLocaleString()})`,
+      );
+      lines.push(
+        "Strike | Bid/Ask (per share) | Last (per share) | Vol | OI | IV | Delta | Gamma | Theta | Vega | Rho",
+      );
       const topPuts = sortByVolume(chain.puts).slice(0, 10);
       for (const c of topPuts) {
         lines.push(formatContract(c));
@@ -77,6 +95,17 @@ export const optionChainTool: AgentTool<typeof params, OptionsChain> = {
   },
 };
 
+function parseExpiration(expiration: string): number {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(expiration)) {
+    throw new Error("expiration must be a valid YYYY-MM-DD date.");
+  }
+  const parsed = new Date(`${expiration}T00:00:00.000Z`);
+  if (Number.isNaN(parsed.getTime()) || parsed.toISOString().slice(0, 10) !== expiration) {
+    throw new Error("expiration must be a valid YYYY-MM-DD date.");
+  }
+  return Math.floor(parsed.getTime() / 1000);
+}
+
 function sortByVolume(contracts: OptionContract[]): OptionContract[] {
   return [...contracts].sort((a, b) => b.volume - a.volume);
 }
@@ -87,5 +116,5 @@ function formatAvailableExpirations(expirationDates: string[]): string {
 
 function formatContract(c: OptionContract): string {
   const itm = c.inTheMoney ? "*" : " ";
-  return `${itm}$${c.strike.toFixed(2)} | $${c.bid.toFixed(2)}/$${c.ask.toFixed(2)} | $${c.lastPrice.toFixed(2)} | ${c.volume} | ${c.openInterest} | ${(c.impliedVolatility * 100).toFixed(1)}% | ${c.greeks.delta.toFixed(3)} | ${c.greeks.theta.toFixed(3)}`;
+  return `${itm}$${c.strike.toFixed(2)} | $${c.bid.toFixed(2)}/$${c.ask.toFixed(2)} | $${c.lastPrice.toFixed(2)} | ${c.volume} | ${c.openInterest} | ${(c.impliedVolatility * 100).toFixed(1)}% | ${c.greeks.delta.toFixed(3)} | ${c.greeks.gamma.toFixed(3)} | ${c.greeks.theta.toFixed(3)} | ${c.greeks.vega.toFixed(3)} | ${c.greeks.rho.toFixed(3)}`;
 }