@openfinclaw/fin-market-data 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Peter Steinberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/index.test.ts

@@ -0,0 +1,402 @@
+import type { OpenClawPluginApi } from "openfinclaw/plugin-sdk";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import finMarketDataPlugin from "./index.js";
+
+// --- Mock exchange instance ---
+function createMockExchange() {
+  return {
+    fetchTicker: vi.fn(),
+    fetchOHLCV: vi.fn(),
+    fetchOrderBook: vi.fn(),
+    fetchTickers: vi.fn(),
+  };
+}
+
+// --- Mock registry ---
+function createMockRegistry(
+  exchanges: Array<{ id: string; exchange: string; testnet: boolean }> = [],
+) {
+  const instances = new Map<string, ReturnType<typeof createMockExchange>>();
+  for (const ex of exchanges) {
+    instances.set(ex.id, createMockExchange());
+  }
+  return {
+    listExchanges: vi.fn(() => exchanges),
+    getInstance: vi.fn(async (id: string) => {
+      const inst = instances.get(id);
+      if (!inst) throw new Error(`Exchange "${id}" not configured.`);
+      return inst;
+    }),
+    _instances: instances,
+  };
+}
+
+// --- Fake plugin API ---
+function createFakeApi(registry: ReturnType<typeof createMockRegistry> | null): {
+  api: OpenClawPluginApi;
+  tools: Map<
+    string,
+    { execute: (id: string, params: Record<string, unknown>) => Promise<unknown> }
+  >;
+} {
+  const tools = new Map<
+    string,
+    { execute: (id: string, params: Record<string, unknown>) => Promise<unknown> }
+  >();
+  const services = new Map<string, unknown>();
+  if (registry) {
+    services.set("fin-exchange-registry", registry);
+  }
+
+  const api = {
+    id: "fin-market-data",
+    name: "Market Data",
+    source: "test",
+    config: {},
+    pluginConfig: {},
+    runtime: {
+      version: "test",
+      services,
+    },
+    logger: { info() {}, warn() {}, error() {}, debug() {} },
+    registerTool(tool: {
+      name: string;
+      execute: (id: string, params: Record<string, unknown>) => Promise<unknown>;
+    }) {
+      tools.set(tool.name, tool);
+    },
+    registerHook() {},
+    registerHttpHandler() {},
+    registerHttpRoute() {},
+    registerChannel() {},
+    registerGatewayMethod() {},
+    registerCli() {},
+    registerService() {},
+    registerProvider() {},
+    registerCommand() {},
+    resolvePath: (p: string) => p,
+    on() {},
+  } as unknown as OpenClawPluginApi;
+
+  return { api, tools };
+}
+
+function parseResult(result: unknown): unknown {
+  const res = result as { content: Array<{ text: string }> };
+  return JSON.parse(res.content[0]!.text);
+}
+
+describe("fin-market-data plugin", () => {
+  let registry: ReturnType<typeof createMockRegistry>;
+  let tools: Map<
+    string,
+    { execute: (id: string, params: Record<string, unknown>) => Promise<unknown> }
+  >;
+  let mockExchange: ReturnType<typeof createMockExchange>;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    registry = createMockRegistry([{ id: "test-binance", exchange: "binance", testnet: false }]);
+    mockExchange = registry._instances.get("test-binance")!;
+    const { api, tools: t } = createFakeApi(registry);
+    tools = t;
+    finMarketDataPlugin.register(api);
+  });
+
+  describe("fin_market_price", () => {
+    it("returns current price and OHLCV candles", async () => {
+      mockExchange.fetchTicker.mockResolvedValue({
+        last: 67500.5,
+        change: 1200,
+        percentage: 1.81,
+        high: 68000,
+        low: 66200,
+        quoteVolume: 1_500_000_000,
+      });
+      mockExchange.fetchOHLCV.mockResolvedValue([
+        [1708819200000, 67000, 67800, 66900, 67500, 1500],
+        [1708822800000, 67500, 68000, 67200, 67800, 1200],
+      ]);
+
+      const tool = tools.get("fin_market_price")!;
+      const result = parseResult(
+        await tool.execute("call-1", {
+          symbol: "BTC/USDT",
+          timeframe: "1h",
+          limit: 2,
+        }),
+      );
+
+      expect(result).toMatchObject({
+        symbol: "BTC/USDT",
+        exchange: "test-binance",
+        price: 67500.5,
+        changePct24h: 1.81,
+        timeframe: "1h",
+      });
+      const r = result as { candles: unknown[] };
+      expect(r.candles).toHaveLength(2);
+      expect(r.candles[0]).toMatchObject({
+        open: 67000,
+        high: 67800,
+        low: 66900,
+        close: 67500,
+        volume: 1500,
+      });
+
+      expect(mockExchange.fetchTicker).toHaveBeenCalledWith("BTC/USDT");
+      expect(mockExchange.fetchOHLCV).toHaveBeenCalledWith("BTC/USDT", "1h", undefined, 2);
+    });
+
+    it("uses default exchange when not specified", async () => {
+      mockExchange.fetchTicker.mockResolvedValue({ last: 67500 });
+      mockExchange.fetchOHLCV.mockResolvedValue([]);
+
+      const tool = tools.get("fin_market_price")!;
+      await tool.execute("call-2", { symbol: "BTC/USDT" });
+
+      expect(registry.getInstance).toHaveBeenCalledWith("test-binance");
+    });
+
+    it("uses explicit exchange when specified", async () => {
+      mockExchange.fetchTicker.mockResolvedValue({ last: 67500 });
+      mockExchange.fetchOHLCV.mockResolvedValue([]);
+
+      const tool = tools.get("fin_market_price")!;
+      await tool.execute("call-3", { symbol: "BTC/USDT", exchange: "test-binance" });
+
+      expect(registry.getInstance).toHaveBeenCalledWith("test-binance");
+    });
+
+    it("returns error for CCXT failures", async () => {
+      mockExchange.fetchTicker.mockRejectedValue(new Error("Network error"));
+
+      const tool = tools.get("fin_market_price")!;
+      const result = parseResult(await tool.execute("call-4", { symbol: "BTC/USDT" }));
+
+      expect(result).toMatchObject({ error: "Network error" });
+    });
+  });
+
+  describe("fin_ticker_info", () => {
+    it("returns detailed ticker info", async () => {
+      mockExchange.fetchTicker.mockResolvedValue({
+        last: 3400.25,
+        bid: 3400.0,
+        ask: 3400.5,
+        high: 3500,
+        low: 3300,
+        open: 3350,
+        close: 3400.25,
+        baseVolume: 250_000,
+        quoteVolume: 850_000_000,
+        change: 50.25,
+        percentage: 1.5,
+        vwap: 3380.5,
+        datetime: "2026-02-24T12:00:00Z",
+      });
+
+      const tool = tools.get("fin_ticker_info")!;
+      const result = parseResult(await tool.execute("call-5", { symbol: "ETH/USDT" }));
+
+      expect(result).toMatchObject({
+        symbol: "ETH/USDT",
+        exchange: "test-binance",
+        last: 3400.25,
+        bid: 3400.0,
+        ask: 3400.5,
+        high24h: 3500,
+        low24h: 3300,
+        volume24h: 250_000,
+        quoteVolume24h: 850_000_000,
+        change24h: 50.25,
+        changePct24h: 1.5,
+        vwap: 3380.5,
+        timestamp: "2026-02-24T12:00:00Z",
+      });
+    });
+
+    it("returns error on auth failure", async () => {
+      mockExchange.fetchTicker.mockRejectedValue(new Error("AuthenticationError: Invalid API key"));
+
+      const tool = tools.get("fin_ticker_info")!;
+      const result = parseResult(await tool.execute("call-6", { symbol: "ETH/USDT" }));
+
+      expect(result).toMatchObject({ error: "AuthenticationError: Invalid API key" });
+    });
+  });
+
+  describe("fin_orderbook", () => {
+    it("returns bids, asks, and spread info", async () => {
+      mockExchange.fetchOrderBook.mockResolvedValue({
+        bids: [
+          [67500, 1.5],
+          [67490, 2.0],
+          [67480, 3.0],
+        ],
+        asks: [
+          [67510, 1.2],
+          [67520, 2.5],
+          [67530, 1.8],
+        ],
+        timestamp: 1708819200000,
+      });
+
+      const tool = tools.get("fin_orderbook")!;
+      const result = parseResult(
+        await tool.execute("call-7", {
+          symbol: "BTC/USDT",
+          limit: 3,
+        }),
+      ) as Record<string, unknown>;
+
+      expect(result.symbol).toBe("BTC/USDT");
+      expect(result.exchange).toBe("test-binance");
+      expect(result.spread).toBe(10);
+      expect(result.spreadPct).toBeCloseTo(0.0148, 3);
+      expect((result.bids as unknown[]).length).toBe(3);
+      expect((result.asks as unknown[]).length).toBe(3);
+      expect(result.bidDepthUsd).toBeGreaterThan(0);
+      expect(result.askDepthUsd).toBeGreaterThan(0);
+
+      expect(mockExchange.fetchOrderBook).toHaveBeenCalledWith("BTC/USDT", 3);
+    });
+
+    it("handles empty orderbook", async () => {
+      mockExchange.fetchOrderBook.mockResolvedValue({
+        bids: [],
+        asks: [],
+        timestamp: null,
+      });
+
+      const tool = tools.get("fin_orderbook")!;
+      const result = parseResult(
+        await tool.execute("call-8", {
+          symbol: "RARE/USDT",
+        }),
+      ) as Record<string, unknown>;
+
+      expect(result.spread).toBeNull();
+      expect(result.spreadPct).toBeNull();
+      expect((result.bids as unknown[]).length).toBe(0);
+      expect((result.asks as unknown[]).length).toBe(0);
+    });
+  });
+
+  describe("fin_market_overview", () => {
+    it("returns sorted tickers with summary stats", async () => {
+      mockExchange.fetchTickers.mockResolvedValue({
+        "BTC/USDT": {
+          symbol: "BTC/USDT",
+          last: 67500,
+          change: 1200,
+          percentage: 1.8,
+          quoteVolume: 1_500_000_000,
+          high: 68000,
+          low: 66200,
+        },
+        "ETH/USDT": {
+          symbol: "ETH/USDT",
+          last: 3400,
+          change: -50,
+          percentage: -1.5,
+          quoteVolume: 800_000_000,
+          high: 3500,
+          low: 3300,
+        },
+        "SOL/USDT": {
+          symbol: "SOL/USDT",
+          last: 145,
+          change: 5,
+          percentage: 3.5,
+          quoteVolume: 200_000_000,
+          high: 150,
+          low: 140,
+        },
+      });
+
+      const tool = tools.get("fin_market_overview")!;
+
+      // Default sort by volume
+      const result = parseResult(await tool.execute("call-9", {})) as Record<string, unknown>;
+      expect(result.totalTickers).toBe(3);
+      expect((result.summary as Record<string, unknown>).gainers).toBe(2);
+      expect((result.summary as Record<string, unknown>).losers).toBe(1);
+
+      const tickers = result.tickers as Array<{ symbol: string; volume24h: number }>;
+      expect(tickers[0]!.symbol).toBe("BTC/USDT");
+      expect(tickers[0]!.volume24h).toBe(1_500_000_000);
+
+      // Sort by change
+      const changeResult = parseResult(
+        await tool.execute("call-10", { sort_by: "change" }),
+      ) as Record<string, unknown>;
+      const changeTickers = changeResult.tickers as Array<{ symbol: string }>;
+      expect(changeTickers[0]!.symbol).toBe("SOL/USDT");
+    });
+
+    it("respects limit parameter", async () => {
+      mockExchange.fetchTickers.mockResolvedValue({
+        "BTC/USDT": {
+          symbol: "BTC/USDT",
+          last: 67500,
+          percentage: 1.8,
+          quoteVolume: 1_500_000_000,
+        },
+        "ETH/USDT": { symbol: "ETH/USDT", last: 3400, percentage: -1.5, quoteVolume: 800_000_000 },
+        "SOL/USDT": { symbol: "SOL/USDT", last: 145, percentage: 3.5, quoteVolume: 200_000_000 },
+      });
+
+      const tool = tools.get("fin_market_overview")!;
+      const result = parseResult(await tool.execute("call-11", { limit: 1 })) as Record<
+        string,
+        unknown
+      >;
+      expect((result.tickers as unknown[]).length).toBe(1);
+    });
+  });
+
+  describe("error scenarios", () => {
+    it("returns friendly error when no exchanges configured", async () => {
+      const emptyRegistry = createMockRegistry([]);
+      const { api, tools: emptyTools } = createFakeApi(emptyRegistry);
+      finMarketDataPlugin.register(api);
+
+      const tool = emptyTools.get("fin_market_price")!;
+      const result = parseResult(
+        await tool.execute("call-err-1", {
+          symbol: "BTC/USDT",
+        }),
+      ) as Record<string, unknown>;
+
+      expect(result.error).toContain("No exchanges configured");
+      expect(result.error).toContain("openfinclaw exchange add");
+    });
+
+    it("returns error when fin-core not loaded", async () => {
+      const { api, tools: noRegistryTools } = createFakeApi(null);
+      finMarketDataPlugin.register(api);
+
+      const tool = noRegistryTools.get("fin_market_price")!;
+      const result = parseResult(
+        await tool.execute("call-err-2", {
+          symbol: "BTC/USDT",
+        }),
+      ) as Record<string, unknown>;
+
+      expect(result.error).toContain("exchange registry unavailable");
+    });
+
+    it("returns error for unknown exchange id", async () => {
+      const tool = tools.get("fin_market_price")!;
+      const result = parseResult(
+        await tool.execute("call-err-3", {
+          symbol: "BTC/USDT",
+          exchange: "nonexistent",
+        }),
+      ) as Record<string, unknown>;
+
+      expect(result.error).toContain("nonexistent");
+    });
+  });
+});

package/index.ts

@@ -0,0 +1,333 @@
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginApi } from "openfinclaw/plugin-sdk";
+
+type ExchangeRegistry = {
+  getInstance: (id: string) => Promise<unknown>;
+  listExchanges: () => Array<{ id: string; exchange: string; testnet: boolean }>;
+};
+
+type CcxtExchange = {
+  fetchTicker: (symbol: string) => Promise<Record<string, unknown>>;
+  fetchOHLCV: (
+    symbol: string,
+    timeframe: string,
+    since?: number,
+    limit?: number,
+  ) => Promise<Array<[number, number, number, number, number, number]>>;
+  fetchOrderBook: (symbol: string, limit?: number) => Promise<Record<string, unknown>>;
+  fetchTickers: (symbols?: string[]) => Promise<Record<string, Record<string, unknown>>>;
+};
+
+const json = (payload: unknown) => ({
+  content: [{ type: "text" as const, text: JSON.stringify(payload, null, 2) }],
+  details: payload,
+});
+
+/** Resolve the ExchangeRegistry service from fin-core. */
+function getRegistry(api: OpenClawPluginApi): ExchangeRegistry {
+  const runtime = api.runtime as unknown as { services?: Map<string, unknown> };
+  const registry = runtime.services?.get?.("fin-exchange-registry") as ExchangeRegistry | undefined;
+  if (!registry) {
+    throw new Error("fin-core plugin not loaded — exchange registry unavailable");
+  }
+  return registry;
+}
+
+/** Resolve a CCXT exchange instance, falling back to the first configured exchange. */
+async function resolveExchange(
+  api: OpenClawPluginApi,
+  exchangeId: string | undefined,
+): Promise<{ exchange: CcxtExchange; exchangeId: string }> {
+  const registry = getRegistry(api);
+
+  let id = exchangeId;
+  if (!id || id === "default") {
+    const exchanges = registry.listExchanges();
+    if (exchanges.length === 0) {
+      throw new Error(
+        "No exchanges configured. Run: openfinclaw exchange add <name> --exchange binance --api-key <key> --secret <secret>",
+      );
+    }
+    id = exchanges[0]!.id;
+  }
+
+  const instance = await registry.getInstance(id);
+  return { exchange: instance as CcxtExchange, exchangeId: id };
+}
+
+const finMarketDataPlugin = {
+  id: "fin-market-data",
+  name: "Market Data",
+  description: "Real-time and historical market data tools: prices, orderbooks, tickers",
+  kind: "financial" as const,
+
+  register(api: OpenClawPluginApi) {
+    // --- fin_market_price ---
+    api.registerTool(
+      {
+        name: "fin_market_price",
+        label: "Market Price",
+        description: "Fetch current price or historical OHLCV candles for a trading pair",
+        parameters: Type.Object({
+          symbol: Type.String({ description: "Trading pair symbol (e.g. BTC/USDT, ETH/USDT)" }),
+          exchange: Type.Optional(
+            Type.String({
+              description: "Exchange ID to query (e.g. binance, okx). Uses default if omitted.",
+            }),
+          ),
+          timeframe: Type.Optional(
+            Type.Unsafe<"1m" | "5m" | "1h" | "4h" | "1d">({
+              type: "string",
+              enum: ["1m", "5m", "1h", "4h", "1d"],
+              description: "Candle timeframe for historical OHLCV data",
+            }),
+          ),
+          limit: Type.Optional(
+            Type.Number({ description: "Number of candles to return (default 100)" }),
+          ),
+        }),
+        async execute(_id: string, params: Record<string, unknown>) {
+          try {
+            const symbol = params.symbol as string;
+            const timeframe = (params.timeframe as string | undefined) ?? "1h";
+            const limit = (params.limit as number | undefined) ?? 100;
+
+            const { exchange, exchangeId } = await resolveExchange(
+              api,
+              params.exchange as string | undefined,
+            );
+
+            // Fetch current ticker for latest price
+            const ticker = await exchange.fetchTicker(symbol);
+
+            // Fetch OHLCV candles
+            const candles = await exchange.fetchOHLCV(symbol, timeframe, undefined, limit);
+            const formattedCandles = candles.map(([ts, open, high, low, close, volume]) => ({
+              timestamp: new Date(ts).toISOString(),
+              open,
+              high,
+              low,
+              close,
+              volume,
+            }));
+
+            return json({
+              symbol,
+              exchange: exchangeId,
+              price: ticker.last,
+              change24h: ticker.change,
+              changePct24h: ticker.percentage,
+              high24h: ticker.high,
+              low24h: ticker.low,
+              volume24h: ticker.quoteVolume,
+              timeframe,
+              candles: formattedCandles,
+            });
+          } catch (err) {
+            return json({ error: err instanceof Error ? err.message : String(err) });
+          }
+        },
+      },
+      { names: ["fin_market_price"] },
+    );
+
+    // --- fin_market_overview ---
+    api.registerTool(
+      {
+        name: "fin_market_overview",
+        label: "Market Overview",
+        description:
+          "Get market overview with top movers, volume leaders, and market summary from an exchange",
+        parameters: Type.Object({
+          exchange: Type.Optional(
+            Type.String({ description: "Exchange ID to query. Uses default if omitted." }),
+          ),
+          sort_by: Type.Optional(
+            Type.Unsafe<"change" | "volume" | "price">({
+              type: "string",
+              enum: ["change", "volume", "price"],
+              description: "Sort tickers by: change (24h %), volume, or price (default: volume)",
+            }),
+          ),
+          limit: Type.Optional(
+            Type.Number({ description: "Number of top tickers to return (default 20)" }),
+          ),
+        }),
+        async execute(_id: string, params: Record<string, unknown>) {
+          try {
+            const sortBy = (params.sort_by as string | undefined) ?? "volume";
+            const limit = (params.limit as number | undefined) ?? 20;
+
+            const { exchange, exchangeId } = await resolveExchange(
+              api,
+              params.exchange as string | undefined,
+            );
+
+            const tickers = await exchange.fetchTickers();
+            const tickerList = Object.values(tickers)
+              .filter((t) => t.last != null && t.quoteVolume != null)
+              .map((t) => ({
+                symbol: t.symbol as string,
+                price: t.last as number,
+                change24h: (t.change as number) ?? 0,
+                changePct24h: (t.percentage as number) ?? 0,
+                volume24h: (t.quoteVolume as number) ?? 0,
+                high24h: t.high as number | null,
+                low24h: t.low as number | null,
+              }));
+
+            // Sort
+            if (sortBy === "change") {
+              tickerList.sort((a, b) => Math.abs(b.changePct24h) - Math.abs(a.changePct24h));
+            } else if (sortBy === "price") {
+              tickerList.sort((a, b) => b.price - a.price);
+            } else {
+              tickerList.sort((a, b) => b.volume24h - a.volume24h);
+            }
+
+            const topTickers = tickerList.slice(0, limit);
+
+            // Compute summary stats
+            const gainers = tickerList.filter((t) => t.changePct24h > 0).length;
+            const losers = tickerList.filter((t) => t.changePct24h < 0).length;
+            const totalVolume = tickerList.reduce((sum, t) => sum + t.volume24h, 0);
+
+            return json({
+              exchange: exchangeId,
+              totalTickers: tickerList.length,
+              summary: {
+                gainers,
+                losers,
+                unchanged: tickerList.length - gainers - losers,
+                totalVolume24h: totalVolume,
+              },
+              sortedBy: sortBy,
+              tickers: topTickers,
+            });
+          } catch (err) {
+            return json({ error: err instanceof Error ? err.message : String(err) });
+          }
+        },
+      },
+      { names: ["fin_market_overview"] },
+    );
+
+    // --- fin_orderbook ---
+    api.registerTool(
+      {
+        name: "fin_orderbook",
+        label: "Order Book",
+        description: "Fetch order book depth showing bids and asks for a trading pair",
+        parameters: Type.Object({
+          symbol: Type.String({ description: "Trading pair symbol (e.g. BTC/USDT)" }),
+          exchange: Type.Optional(
+            Type.String({ description: "Exchange ID to query. Uses default if omitted." }),
+          ),
+          limit: Type.Optional(
+            Type.Number({
+              description: "Depth limit — number of price levels per side (default 25)",
+            }),
+          ),
+        }),
+        async execute(_id: string, params: Record<string, unknown>) {
+          try {
+            const symbol = params.symbol as string;
+            const limit = (params.limit as number | undefined) ?? 25;
+
+            const { exchange, exchangeId } = await resolveExchange(
+              api,
+              params.exchange as string | undefined,
+            );
+
+            const book = await exchange.fetchOrderBook(symbol, limit);
+
+            const bids = (book.bids as Array<[number, number]>).map(([price, amount]) => ({
+              price,
+              amount,
+            }));
+            const asks = (book.asks as Array<[number, number]>).map(([price, amount]) => ({
+              price,
+              amount,
+            }));
+
+            const bidTotal = bids.reduce((s, b) => s + b.price * b.amount, 0);
+            const askTotal = asks.reduce((s, a) => s + a.price * a.amount, 0);
+            const spread =
+              asks.length > 0 && bids.length > 0 ? asks[0]!.price - bids[0]!.price : null;
+            const spreadPct =
+              spread != null && bids[0]!.price > 0 ? (spread / bids[0]!.price) * 100 : null;
+
+            return json({
+              symbol,
+              exchange: exchangeId,
+              timestamp: book.timestamp
+                ? new Date(book.timestamp as number).toISOString()
+                : new Date().toISOString(),
+              spread,
+              spreadPct: spreadPct != null ? Number(spreadPct.toFixed(4)) : null,
+              bidDepthUsd: Number(bidTotal.toFixed(2)),
+              askDepthUsd: Number(askTotal.toFixed(2)),
+              bids,
+              asks,
+            });
+          } catch (err) {
+            return json({ error: err instanceof Error ? err.message : String(err) });
+          }
+        },
+      },
+      { names: ["fin_orderbook"] },
+    );
+
+    // --- fin_ticker_info ---
+    api.registerTool(
+      {
+        name: "fin_ticker_info",
+        label: "Ticker Info",
+        description: "Get detailed ticker information including 24h volume, price change, high/low",
+        parameters: Type.Object({
+          symbol: Type.String({
+            description: "Trading pair symbol (e.g. BTC/USDT, ETH/BTC)",
+          }),
+          exchange: Type.Optional(
+            Type.String({ description: "Exchange ID to query. Uses default if omitted." }),
+          ),
+        }),
+        async execute(_id: string, params: Record<string, unknown>) {
+          try {
+            const symbol = params.symbol as string;
+
+            const { exchange, exchangeId } = await resolveExchange(
+              api,
+              params.exchange as string | undefined,
+            );
+
+            const ticker = await exchange.fetchTicker(symbol);
+
+            return json({
+              symbol,
+              exchange: exchangeId,
+              last: ticker.last,
+              bid: ticker.bid,
+              ask: ticker.ask,
+              high24h: ticker.high,
+              low24h: ticker.low,
+              open24h: ticker.open,
+              close24h: ticker.close,
+              volume24h: ticker.baseVolume,
+              quoteVolume24h: ticker.quoteVolume,
+              change24h: ticker.change,
+              changePct24h: ticker.percentage,
+              vwap: ticker.vwap,
+              timestamp: ticker.datetime ?? new Date().toISOString(),
+            });
+          } catch (err) {
+            return json({ error: err instanceof Error ? err.message : String(err) });
+          }
+        },
+      },
+      { names: ["fin_ticker_info"] },
+    );
+  },
+};
+
+export default finMarketDataPlugin;

package/openclaw.plugin.json

@@ -0,0 +1,11 @@
+{
+  "id": "fin-market-data",
+  "name": "Market Data",
+  "description": "Real-time and historical market data tools: prices, orderbooks, tickers",
+  "kind": "financial",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@openfinclaw/fin-market-data",
+  "version": "0.0.1",
+  "description": "OpenFinClaw market data tools — prices, orderbooks, tickers, market overview",
+  "keywords": [
+    "financial",
+    "market-data",
+    "openclaw",
+    "openfinclaw",
+    "trading"
+  ],
+  "homepage": "https://github.com/cryptoSUN2049/openFinclaw#readme",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cryptoSUN2049/openFinclaw.git",
+    "directory": "extensions/fin-market-data"
+  },
+  "files": [
+    "*.ts",
+    "src",
+    "openclaw.plugin.json"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "devDependencies": {
+    "openfinclaw": "2026.3.3"
+  },
+  "peerDependencies": {
+    "openfinclaw": ">=2026.2.0"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

package/src/llm-finance-pipeline.live.test.ts

@@ -0,0 +1,303 @@
+/**
+ * Real E2E: LLM tool-calling -> fin-market-data -> Binance testnet -> final answer.
+ *
+ * Requires:
+ * - LIVE=1 (or OPENCLAW_LIVE_TEST=1)
+ * - BINANCE_TESTNET_API_KEY
+ * - BINANCE_TESTNET_SECRET
+ * - OPENAI_API_KEY
+ *
+ * Optional:
+ * - OPENAI_BASE_URL (OpenAI-compatible endpoint)
+ * - OPENCLAW_FIN_LIVE_MODEL (default: gpt-5.2)
+ * - OPENCLAW_FIN_LIVE_MODEL_API (openai-completions | openai-responses)
+ */
+import { type Api, completeSimple, getModel, type Model } from "@mariozechner/pi-ai";
+import type { OpenClawPluginApi } from "openfinclaw/plugin-sdk";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { isTruthyEnvValue } from "../../../src/infra/env.js";
+import { ExchangeRegistry } from "../../fin-core/src/exchange-registry.js";
+import finMarketDataPlugin from "../index.js";
+
+type ToolSchema = {
+  name: string;
+  description?: string;
+  parameters?: unknown;
+};
+
+type RegisteredTool = ToolSchema & {
+  execute: (id: string, params: Record<string, unknown>) => Promise<unknown>;
+};
+
+const LIVE = isTruthyEnvValue(process.env.LIVE) || isTruthyEnvValue(process.env.OPENCLAW_LIVE_TEST);
+const API_KEY = process.env.BINANCE_TESTNET_API_KEY ?? "";
+const SECRET = process.env.BINANCE_TESTNET_SECRET ?? "";
+const OPENAI_API_KEY = process.env.OPENAI_API_KEY ?? "";
+const OPENAI_BASE_URL = process.env.OPENAI_BASE_URL?.trim() || "";
+const MODEL_API =
+  (process.env.OPENCLAW_FIN_LIVE_MODEL_API?.trim() as
+    | "openai-completions"
+    | "openai-responses"
+    | "") || (OPENAI_BASE_URL ? "openai-completions" : "openai-responses");
+const MODEL_ID =
+  process.env.OPENCLAW_FIN_LIVE_MODEL?.trim() ||
+  (MODEL_API === "openai-completions" ? "gpt-4o-mini" : "gpt-5.2");
+
+const describeLive = LIVE && API_KEY && SECRET && OPENAI_API_KEY ? describe : describe.skip;
+
+function parseToolResult(result: unknown): Record<string, unknown> {
+  const content = (result as { content?: Array<{ text?: string }> }).content;
+  const raw = content?.[0]?.text;
+  if (!raw) {
+    throw new Error("tool result missing JSON text content");
+  }
+  const parsed = JSON.parse(raw) as Record<string, unknown>;
+  return parsed;
+}
+
+function parseToolArguments(value: unknown): Record<string, unknown> {
+  if (!value) return {};
+  if (typeof value === "string") {
+    try {
+      return JSON.parse(value) as Record<string, unknown>;
+    } catch {
+      return {};
+    }
+  }
+  if (typeof value === "object") {
+    return value as Record<string, unknown>;
+  }
+  return {};
+}
+
+function assertNoModelError(message: {
+  stopReason?: string;
+  errorMessage?: string;
+  content?: unknown[];
+}): void {
+  if (message.stopReason === "error") {
+    throw new Error(`model request failed: ${message.errorMessage ?? "unknown error"}`);
+  }
+}
+
+function createFakeApi(registry: ExchangeRegistry): {
+  api: OpenClawPluginApi;
+  tools: Map<string, RegisteredTool>;
+} {
+  const tools = new Map<string, RegisteredTool>();
+  const services = new Map<string, unknown>();
+  services.set("fin-exchange-registry", registry);
+
+  const api = {
+    id: "fin-market-data",
+    name: "Market Data",
+    source: "live-test",
+    config: {},
+    pluginConfig: {},
+    runtime: {
+      version: "live-test",
+      services,
+    },
+    logger: { info() {}, warn() {}, error() {}, debug() {} },
+    registerTool(tool: {
+      name: string;
+      description?: string;
+      parameters?: unknown;
+      execute: (id: string, params: Record<string, unknown>) => Promise<unknown>;
+    }) {
+      tools.set(tool.name, {
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.parameters,
+        execute: tool.execute,
+      });
+    },
+    registerHook() {},
+    registerHttpHandler() {},
+    registerHttpRoute() {},
+    registerChannel() {},
+    registerGatewayMethod() {},
+    registerCli() {},
+    registerService() {},
+    registerProvider() {},
+    registerCommand() {},
+    resolvePath: (p: string) => p,
+    on() {},
+  } as unknown as OpenClawPluginApi;
+
+  return { api, tools };
+}
+
+describeLive("finance llm full pipeline (live)", () => {
+  let registry: ExchangeRegistry;
+  let tool: RegisteredTool;
+  let model: Model<Api>;
+
+  beforeAll(async () => {
+    registry = new ExchangeRegistry();
+    registry.addExchange("binance-testnet", {
+      exchange: "binance",
+      apiKey: API_KEY,
+      secret: SECRET,
+      testnet: true,
+      defaultType: "spot",
+    });
+
+    const { api, tools } = createFakeApi(registry);
+    finMarketDataPlugin.register(api);
+
+    const marketPriceTool = tools.get("fin_market_price");
+    if (!marketPriceTool) {
+      throw new Error("fin_market_price tool not registered");
+    }
+    tool = marketPriceTool;
+
+    if (MODEL_API === "openai-completions") {
+      model = {
+        id: MODEL_ID,
+        name: `OpenAI Compatible ${MODEL_ID}`,
+        api: "openai-completions",
+        provider: "openai",
+        baseUrl: OPENAI_BASE_URL || "https://api.openai.com/v1",
+        reasoning: false,
+        input: ["text"],
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: 128_000,
+        maxTokens: 8_192,
+      } as unknown as Model<Api>;
+      return;
+    }
+
+    const baseModel = getModel(
+      "openai" as "openai",
+      MODEL_ID as Parameters<typeof getModel>[1],
+    ) as unknown as Model<Api>;
+    model = OPENAI_BASE_URL
+      ? ({ ...baseModel, baseUrl: OPENAI_BASE_URL } as Model<Api>)
+      : baseModel;
+  });
+
+  afterAll(async () => {
+    await registry.closeAll();
+  });
+
+  it("LLM calls fin_market_price then produces grounded summary", async () => {
+    let first = await completeSimple(
+      model,
+      {
+        messages: [
+          {
+            role: "user",
+            content:
+              "Use tool fin_market_price to fetch BTC/USDT from binance-testnet with timeframe 1h limit 5. Return only the tool call.",
+            timestamp: Date.now(),
+          },
+        ],
+        tools: [
+          {
+            name: tool.name,
+            description: tool.description ?? "",
+            parameters: tool.parameters,
+          } as NonNullable<Parameters<typeof completeSimple>[1]["tools"]>[number],
+        ],
+      },
+      { apiKey: OPENAI_API_KEY, maxTokens: 256, reasoning: "minimal" },
+    );
+    assertNoModelError(first);
+
+    let toolCall = first.content.find((block) => block.type === "toolCall");
+    for (let retry = 0; retry < 2 && !toolCall; retry += 1) {
+      first = await completeSimple(
+        model,
+        {
+          messages: [
+            {
+              role: "user",
+              content:
+                'MANDATORY: Call fin_market_price with {"symbol":"BTC/USDT","exchange":"binance-testnet","timeframe":"1h","limit":5}. Reply with tool call only.',
+              timestamp: Date.now(),
+            },
+          ],
+          tools: [
+            {
+              name: tool.name,
+              description: tool.description ?? "",
+              parameters: tool.parameters,
+            } as NonNullable<Parameters<typeof completeSimple>[1]["tools"]>[number],
+          ],
+        },
+        { apiKey: OPENAI_API_KEY, maxTokens: 256, reasoning: "minimal" },
+      );
+      assertNoModelError(first);
+      toolCall = first.content.find((block) => block.type === "toolCall");
+    }
+
+    expect(toolCall).toBeTruthy();
+    if (!toolCall || toolCall.type !== "toolCall") {
+      throw new Error("expected model to issue a tool call");
+    }
+
+    const toolArgs = parseToolArguments(
+      (toolCall as { arguments?: unknown; input?: unknown }).arguments ??
+        (toolCall as { arguments?: unknown; input?: unknown }).input,
+    );
+    const mergedArgs: Record<string, unknown> = {
+      symbol: "BTC/USDT",
+      exchange: "binance-testnet",
+      timeframe: "1h",
+      limit: 5,
+      ...toolArgs,
+    };
+    const rawToolResult = await tool.execute("fin-live-call-1", mergedArgs);
+    const parsedToolResult = parseToolResult(rawToolResult);
+
+    expect(parsedToolResult.error).toBeUndefined();
+    expect(parsedToolResult.symbol).toBe("BTC/USDT");
+    expect(Number(parsedToolResult.price ?? 0)).toBeGreaterThan(0);
+    expect(Array.isArray(parsedToolResult.candles)).toBe(true);
+    expect((parsedToolResult.candles as unknown[]).length).toBeGreaterThan(0);
+
+    const second = await completeSimple(
+      model,
+      {
+        messages: [
+          {
+            role: "user",
+            content:
+              "Use tool fin_market_price to fetch BTC/USDT from binance-testnet with timeframe 1h limit 5. Return only the tool call.",
+            timestamp: Date.now(),
+          },
+          first,
+          {
+            role: "toolResult",
+            toolCallId: toolCall.id,
+            toolName: tool.name,
+            content: [{ type: "text", text: JSON.stringify(parsedToolResult) }],
+            isError: false,
+            timestamp: Date.now(),
+          },
+          {
+            role: "user",
+            content:
+              "Now give one concise sentence summarizing current BTC/USDT price and 24h change from the tool result.",
+            timestamp: Date.now(),
+          },
+        ],
+      },
+      { apiKey: OPENAI_API_KEY, maxTokens: 256, reasoning: "minimal" },
+    );
+    assertNoModelError(second);
+
+    const finalText = second.content
+      .filter((block) => block.type === "text")
+      .map((block) => block.text.trim())
+      .join(" ")
+      .trim();
+
+    expect(finalText.length).toBeGreaterThan(0);
+    expect(/btc|usdt/i.test(finalText)).toBe(true);
+    console.log(
+      `  LLM summary: ${finalText}\n  Tool price: ${parsedToolResult.price}, change%: ${parsedToolResult.changePct24h}`,
+    );
+  }, 45_000);
+});