@blockrun/franklin 3.8.8 → 3.8.9

package/dist/tools/trading.js

@@ -1,4 +1,7 @@
-import { getPrice, getOHLCV, getTrending, getMarketOverview } from '../trading/data.js';
+import { getPrice, getOHLCV, getTrending, getMarketOverview, getFxPrice, getCommodityPrice, getStockPrice, } from '../trading/data.js';
+const SUPPORTED_STOCK_MARKETS = [
+    'us', 'hk', 'jp', 'kr', 'gb', 'de', 'fr', 'nl', 'ie', 'lu', 'cn', 'ca',
+];
 import { rsi, macd, bollingerBands, volatility } from '../trading/metrics.js';
 import { bus } from '../events/bus.js';
 import { makeEvent } from '../events/types.js';
@@ -102,8 +105,17 @@ export const tradingSignalCapability = {
     execute: executeSignal,
     concurrent: true,
 };
+function formatPriceLine(label, priceUsd, change24hPct, opts = {}) {
+    const digits = opts.fractionDigits ?? 2;
+    const priceStr = `$${priceUsd.toLocaleString(undefined, { minimumFractionDigits: digits, maximumFractionDigits: digits })}`;
+    if (opts.showChange === false || !Number.isFinite(change24hPct)) {
+        return `${label}: ${priceStr}`;
+    }
+    const sign = change24hPct > 0 ? '+' : '';
+    return `${label}: ${priceStr} (${sign}${change24hPct.toFixed(2)}% 24h)`;
+}
 async function executeMarket(input, _ctx) {
-    const { action, ticker } = input;
+    const { action, ticker, market } = input;
     if (!action) {
         return { output: 'Error: action is required', isError: true };
     }
@@ -121,6 +133,58 @@ async function executeMarket(input, _ctx) {
                 output: `${ticker.toUpperCase()}: $${price.toLocaleString()} (${change24h > 0 ? '+' : ''}${change24h.toFixed(2)}% 24h), Market Cap: ${formatUsd(marketCap)}, Volume: ${formatUsd(volume24h)}`,
             };
         }
+        case 'fxPrice': {
+            if (!ticker) {
+                return { output: 'Error: ticker is required (e.g. "EUR-USD")', isError: true };
+            }
+            const result = await getFxPrice(ticker);
+            if (typeof result === 'string') {
+                return { output: `Error: ${result}`, isError: true };
+            }
+            return {
+                output: formatPriceLine(ticker.toUpperCase(), result.price, result.change24h, { fractionDigits: 4 }) +
+                    ' · source: BlockRun Gateway / Pyth (free)',
+            };
+        }
+        case 'commodityPrice': {
+            if (!ticker) {
+                return { output: 'Error: ticker is required (e.g. "XAU-USD" for gold)', isError: true };
+            }
+            const result = await getCommodityPrice(ticker);
+            if (typeof result === 'string') {
+                return { output: `Error: ${result}`, isError: true };
+            }
+            return {
+                output: formatPriceLine(ticker.toUpperCase(), result.price, result.change24h, { fractionDigits: 2 }) +
+                    ' · source: BlockRun Gateway / Pyth (free)',
+            };
+        }
+        case 'stockPrice': {
+            if (!ticker) {
+                return { output: 'Error: ticker is required (e.g. "AAPL" on market "us")', isError: true };
+            }
+            if (!market) {
+                return {
+                    output: `Error: market code is required for stockPrice. Supported: ${SUPPORTED_STOCK_MARKETS.join(', ')}`,
+                    isError: true,
+                };
+            }
+            if (!SUPPORTED_STOCK_MARKETS.includes(market)) {
+                return {
+                    output: `Error: unsupported market "${market}". Supported: ${SUPPORTED_STOCK_MARKETS.join(', ')}`,
+                    isError: true,
+                };
+            }
+            const result = await getStockPrice(ticker, market);
+            if (typeof result === 'string') {
+                return { output: `Error: ${result}`, isError: true };
+            }
+            const tickerLabel = `${ticker.toUpperCase()} (${market})`;
+            return {
+                output: formatPriceLine(tickerLabel, result.price, result.change24h, { fractionDigits: 2 }) +
+                    ' · source: BlockRun Gateway / Pyth · $0.001 paid from wallet',
+            };
+        }
         case 'trending': {
             const result = await getTrending();
             if (typeof result === 'string') {
@@ -140,24 +204,39 @@ async function executeMarket(input, _ctx) {
             return { output: `Top 20 by Market Cap:\n${header}\n${sep}\n${rows.join('\n')}` };
         }
         default:
-            return { output: `Error: unknown action "${action}". Use: price, trending, overview`, isError: true };
+            return {
+                output: `Error: unknown action "${action}". Use: price, trending, overview, fxPrice, commodityPrice, stockPrice`,
+                isError: true,
+            };
     }
 }
 export const tradingMarketCapability = {
     spec: {
         name: 'TradingMarket',
-        description: 'Get cryptocurrency market data: price lookup, trending coins, or market overview (top 20 by market cap).',
+        description: 'Get market data across asset classes. Actions: ' +
+            '`price` (crypto spot via CoinGecko, free), ' +
+            '`trending` (top trending coins), ' +
+            '`overview` (top 20 by market cap), ' +
+            '`fxPrice` (FX pair like EUR-USD, BlockRun Gateway/Pyth, free), ' +
+            '`commodityPrice` (XAU-USD for gold, XAG-USD for silver, etc., free), ' +
+            '`stockPrice` (any of 1,746 tickers across us/hk/jp/kr/gb/de/fr/nl/ie/lu/cn/ca, BlockRun Gateway/Pyth, $0.001 per call paid from the agent wallet). ' +
+            'Prefer stockPrice for any equity question — CRCL, AAPL, 7203.JP, 0005.HK, etc.',
         input_schema: {
             type: 'object',
             properties: {
                 action: {
                     type: 'string',
-                    enum: ['price', 'trending', 'overview'],
-                    description: 'What to fetch: price lookup, trending coins, or market overview',
+                    enum: ['price', 'trending', 'overview', 'fxPrice', 'commodityPrice', 'stockPrice'],
+                    description: 'What to fetch. See tool description for cost + source per action.',
                 },
                 ticker: {
                     type: 'string',
-                    description: 'Cryptocurrency ticker (required for price action), e.g. "BTC"',
+                    description: 'Ticker. Crypto: "BTC". FX: "EUR-USD". Commodity: "XAU-USD" (gold). Stock: "AAPL", "CRCL", "7203" (Toyota on jp), "0005" (HSBC on hk). Required for all price actions.',
+                },
+                market: {
+                    type: 'string',
+                    enum: ['us', 'hk', 'jp', 'kr', 'gb', 'de', 'fr', 'nl', 'ie', 'lu', 'cn', 'ca'],
+                    description: 'Stock exchange market code. Required when action="stockPrice". Ignored for other actions.',
                 },
             },
             required: ['action'],

package/dist/tools/webhook.d.ts

@@ -0,0 +1,18 @@
+/**
+ * WebhookPost — generic HTTP POST tool for pushing agent output to any
+ * webhook endpoint. Covers WeChat Work, Feishu, Discord, Slack, Telegram
+ * Bot API, PushPlus, ServerChan, custom HTTP receivers — anything that
+ * accepts a JSON body over POST.
+ *
+ * Intentionally not per-vendor: those integrations differ only in body
+ * shape, which the agent already knows how to construct. One tool, eight
+ * channels. If a channel needs a signature header (e.g., Feishu sign
+ * mode), the agent passes it in via `headers`.
+ *
+ * Safety: outbound URLs are a publish surface. We refuse localhost,
+ * private ranges, and file schemes so an agent can't be tricked into
+ * hitting internal services. A permission prompt fires on first use per
+ * session.
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+export declare const webhookPostCapability: CapabilityHandler;

package/dist/tools/webhook.js

@@ -0,0 +1,185 @@
+/**
+ * WebhookPost — generic HTTP POST tool for pushing agent output to any
+ * webhook endpoint. Covers WeChat Work, Feishu, Discord, Slack, Telegram
+ * Bot API, PushPlus, ServerChan, custom HTTP receivers — anything that
+ * accepts a JSON body over POST.
+ *
+ * Intentionally not per-vendor: those integrations differ only in body
+ * shape, which the agent already knows how to construct. One tool, eight
+ * channels. If a channel needs a signature header (e.g., Feishu sign
+ * mode), the agent passes it in via `headers`.
+ *
+ * Safety: outbound URLs are a publish surface. We refuse localhost,
+ * private ranges, and file schemes so an agent can't be tricked into
+ * hitting internal services. A permission prompt fires on first use per
+ * session.
+ */
+import { isIP } from 'node:net';
+const DEFAULT_TIMEOUT_MS = 15_000;
+const MAX_BODY_BYTES = 512 * 1024; // 512 KB is generous for a chat push.
+function isPrivateHost(hostname) {
+    const h = hostname
+        .trim()
+        .replace(/^\[/, '')
+        .replace(/\]$/, '')
+        .split('%', 1)[0]
+        .toLowerCase();
+    if (h === 'localhost' || h === '127.0.0.1' || h === '0.0.0.0' || h === '::' || h === '::1')
+        return true;
+    // IPv4 private ranges.
+    if (isIP(h) === 4) {
+        const m = /^(\d+)\.(\d+)\.(\d+)\.(\d+)$/.exec(h);
+        if (m) {
+            const [a, b] = [Number(m[1]), Number(m[2])];
+            if (a === 10)
+                return true;
+            if (a === 172 && b >= 16 && b <= 31)
+                return true;
+            if (a === 192 && b === 168)
+                return true;
+            if (a === 169 && b === 254)
+                return true; // link-local
+            if (a === 127)
+                return true;
+        }
+    }
+    if (isIP(h) === 6) {
+        if (h.startsWith('fc') || h.startsWith('fd') || h.startsWith('fe80:'))
+            return true;
+        if (h.startsWith('::ffff:')) {
+            return isPrivateHost(h.slice('::ffff:'.length));
+        }
+    }
+    return false;
+}
+async function execute(input, ctx) {
+    const { url, body, headers, method = 'POST' } = input;
+    if (!url || typeof url !== 'string') {
+        return { output: 'Error: url is required (string).', isError: true };
+    }
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return { output: `Error: invalid URL: ${url}`, isError: true };
+    }
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+        return { output: `Error: only http(s) URLs allowed, got ${parsed.protocol}`, isError: true };
+    }
+    if (isPrivateHost(parsed.hostname)) {
+        return {
+            output: `Error: refusing to post to private/loopback host ${parsed.hostname}. ` +
+                `WebhookPost is for public webhook endpoints only.`,
+            isError: true,
+        };
+    }
+    // Serialize body. Accept object/array (JSON.stringify) or string (used as-is).
+    let bodyText;
+    let contentType = 'application/json';
+    if (typeof body === 'string') {
+        bodyText = body;
+        contentType = 'text/plain';
+    }
+    else if (body === undefined || body === null) {
+        bodyText = '';
+    }
+    else {
+        try {
+            bodyText = JSON.stringify(body);
+        }
+        catch (err) {
+            return { output: `Error: body is not JSON-serializable: ${err.message}`, isError: true };
+        }
+    }
+    const bodyBytes = Buffer.byteLength(bodyText, 'utf-8');
+    if (bodyBytes > MAX_BODY_BYTES) {
+        return {
+            output: `Error: body is ${(bodyBytes / 1024).toFixed(1)} KB, exceeds ${MAX_BODY_BYTES / 1024} KB cap.`,
+            isError: true,
+        };
+    }
+    const finalHeaders = {
+        'Content-Type': contentType,
+        'User-Agent': 'franklin/3.8.9 (webhook)',
+        ...(headers ?? {}),
+    };
+    const ctrl = new AbortController();
+    // Chain abort from the execution scope so Ctrl+C cancels the webhook call.
+    const onParentAbort = () => ctrl.abort();
+    ctx.abortSignal.addEventListener('abort', onParentAbort);
+    const timer = setTimeout(() => ctrl.abort(), DEFAULT_TIMEOUT_MS);
+    try {
+        const res = await fetch(url, {
+            method,
+            headers: finalHeaders,
+            body: bodyText || undefined,
+            signal: ctrl.signal,
+        });
+        // Capture a small slice of the response body for debugging — most webhook
+        // endpoints return a short ack ({"ok":true}, "ok", "1", etc.).
+        const text = await res.text();
+        const preview = text.length > 500 ? text.slice(0, 500) + '...' : text;
+        if (!res.ok) {
+            return {
+                output: `Webhook POST failed: HTTP ${res.status} ${res.statusText}\nResponse: ${preview}`,
+                isError: true,
+            };
+        }
+        return {
+            output: `Posted ${bodyBytes}B to ${parsed.host}${parsed.pathname}\n` +
+                `Response ${res.status}: ${preview || '(empty)'}`,
+        };
+    }
+    catch (err) {
+        if (err.name === 'AbortError') {
+            if (ctx.abortSignal.aborted)
+                return { output: 'Webhook POST canceled by user.', isError: true };
+            return { output: `Webhook POST timed out after ${DEFAULT_TIMEOUT_MS}ms`, isError: true };
+        }
+        return { output: `Webhook POST error: ${err.message}`, isError: true };
+    }
+    finally {
+        clearTimeout(timer);
+        ctx.abortSignal.removeEventListener('abort', onParentAbort);
+    }
+}
+export const webhookPostCapability = {
+    spec: {
+        name: 'WebhookPost',
+        description: 'POST a JSON or plain-text payload to a webhook URL. Works with any service that ' +
+            'accepts an HTTP POST: WeChat Work bots, Feishu/Lark bots, Discord/Slack webhooks, ' +
+            'Telegram Bot API (sendMessage), PushPlus, ServerChan, or a custom receiver. ' +
+            'The agent is responsible for the body shape — each channel has its own schema ' +
+            '(e.g., Discord: { "content": "hello" }; WeChat Work: { "msgtype": "markdown", ' +
+            '"markdown": { "content": "..." } }).\n\n' +
+            'Safety: private/loopback hosts are refused. Bodies over 512KB are refused. ' +
+            'Do NOT use for GET requests — use WebFetch for reads.',
+        input_schema: {
+            type: 'object',
+            required: ['url', 'body'],
+            properties: {
+                url: {
+                    type: 'string',
+                    description: 'Full https (or http) webhook URL. Must be a public host.',
+                },
+                body: {
+                    description: 'Request body. Pass an object/array → JSON.stringify. Pass a string → sent ' +
+                        'as text/plain. Construct the shape each channel expects.',
+                },
+                headers: {
+                    type: 'object',
+                    description: 'Optional extra request headers (auth tokens, signing headers). Content-Type ' +
+                        'is set automatically based on body type.',
+                },
+                method: {
+                    type: 'string',
+                    enum: ['POST', 'PUT', 'PATCH'],
+                    description: 'HTTP method. Defaults to POST.',
+                },
+            },
+        },
+    },
+    execute,
+    concurrent: false,
+};

package/dist/trading/data.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Legacy data.ts — thin shim over the provider registry.
+ *
+ * Keeps the historical `string | Data` error-by-string return convention so
+ * the existing callers (`trading.ts`, `tools/index.ts` wiring into
+ * `LiveExchange`) keep working without a call-site rewrite. New code should
+ * import from `./providers/registry.js` and consume `PriceData | ProviderError`
+ * directly — the structured error shape enables UI color-coding and retry
+ * classification the string convention can't express.
+ */
+import type { AssetClass, MarketCode } from './providers/standard-models.js';
 export interface PriceData {
     price: number;
     change24h: number;
@@ -24,7 +35,19 @@ export interface MarketCoin {
     volume24h: number;
 }
 export declare function resolveId(ticker: string): string;
-export declare function getPrice(ticker: string): Promise<PriceData | string>;
+/**
+ * Look up a spot price. `assetClass` defaults to 'crypto' so all existing
+ * crypto-only callers (`TradingSignal`, `LiveExchange.getPrice`) behave
+ * exactly as before. Pass 'fx' / 'commodity' / 'stock' (plus a `market`
+ * code for stocks) to hit the multi-asset Gateway endpoints.
+ */
+export declare function getPrice(ticker: string, assetClass?: AssetClass, market?: MarketCode): Promise<PriceData | string>;
+/** Convenience: FX pair lookup (e.g. "EUR-USD"). */
+export declare function getFxPrice(ticker: string): Promise<PriceData | string>;
+/** Convenience: commodity lookup (e.g. "XAU-USD" for gold). */
+export declare function getCommodityPrice(ticker: string): Promise<PriceData | string>;
+/** Convenience: stock lookup (e.g. "AAPL" on market "us"). */
+export declare function getStockPrice(ticker: string, market: MarketCode): Promise<PriceData | string>;
 export declare function getOHLCV(ticker: string, days?: number): Promise<OHLCVData | string>;
 export declare function getTrending(): Promise<TrendingCoin[] | string>;
 export declare function getMarketOverview(): Promise<MarketCoin[] | string>;

package/dist/trading/data.js

@@ -1,112 +1,77 @@
-const BASE = "https://api.coingecko.com/api/v3";
-const UA = "franklin/3.3.0 (trading)";
-const TIMEOUT = 10_000;
-const TICKER_MAP = {
-    BTC: "bitcoin", ETH: "ethereum", SOL: "solana", BNB: "binancecoin", XRP: "ripple",
-    ADA: "cardano", DOGE: "dogecoin", AVAX: "avalanche-2", DOT: "polkadot", MATIC: "matic-network",
-    LINK: "chainlink", UNI: "uniswap", ATOM: "cosmos", LTC: "litecoin", NEAR: "near",
-    APT: "aptos", ARB: "arbitrum", OP: "optimism", SUI: "sui", SEI: "sei-network",
-    FIL: "filecoin", AAVE: "aave", MKR: "maker", SNX: "synthetix-network-token",
-    COMP: "compound-governance-token", INJ: "injective-protocol", TIA: "celestia",
-    PEPE: "pepe", WIF: "dogwifcoin", RENDER: "render-token",
-};
-const cache = new Map();
-function cached(key, ttlMs, fn) {
-    const hit = cache.get(key);
-    if (hit && hit.expiry > Date.now())
-        return Promise.resolve(hit.data);
-    return fn().then(data => {
-        cache.set(key, { data, expiry: Date.now() + ttlMs });
-        return data;
-    });
+/**
+ * Legacy data.ts — thin shim over the provider registry.
+ *
+ * Keeps the historical `string | Data` error-by-string return convention so
+ * the existing callers (`trading.ts`, `tools/index.ts` wiring into
+ * `LiveExchange`) keep working without a call-site rewrite. New code should
+ * import from `./providers/registry.js` and consume `PriceData | ProviderError`
+ * directly — the structured error shape enables UI color-coding and retry
+ * classification the string convention can't express.
+ */
+import { getProvider, getPriceProvider } from './providers/registry.js';
+import { runFetcher } from './providers/fetcher.js';
+import { isProviderError } from './providers/standard-models.js';
+export function resolveId(ticker) {
+    // Delegated — kept exported for backwards compat with any external caller.
+    return ticker.toLowerCase();
 }
-const TTL_PRICE = 5 * 60_000;
-const TTL_OHLCV = 60 * 60_000;
-const TTL_TRENDING = 15 * 60_000;
-// Fetch helper
-async function geckofetch(path) {
-    const ctrl = new AbortController();
-    const timer = setTimeout(() => ctrl.abort(), TIMEOUT);
-    try {
-        const res = await fetch(`${BASE}${path}`, {
-            headers: { "User-Agent": UA },
-            signal: ctrl.signal,
-        });
-        if (res.status === 429)
-            return "rate-limited: CoinGecko 429 — retry later";
-        if (!res.ok)
-            return `CoinGecko error ${res.status}`;
-        return await res.json();
-    }
-    catch (e) {
-        if (e instanceof DOMException && e.name === "AbortError")
-            return "request timed out";
-        return String(e);
-    }
-    finally {
-        clearTimeout(timer);
-    }
+/**
+ * Look up a spot price. `assetClass` defaults to 'crypto' so all existing
+ * crypto-only callers (`TradingSignal`, `LiveExchange.getPrice`) behave
+ * exactly as before. Pass 'fx' / 'commodity' / 'stock' (plus a `market`
+ * code for stocks) to hit the multi-asset Gateway endpoints.
+ */
+export async function getPrice(ticker, assetClass = 'crypto', market) {
+    const result = await runFetcher(getPriceProvider(assetClass), { ticker, assetClass, market });
+    if (isProviderError(result))
+        return result.message;
+    return {
+        price: result.priceUsd,
+        change24h: result.change24hPct,
+        volume24h: result.volume24hUsd,
+        marketCap: result.marketCapUsd,
+    };
 }
-export function resolveId(ticker) {
-    return TICKER_MAP[ticker.toUpperCase()] ?? ticker.toLowerCase();
+/** Convenience: FX pair lookup (e.g. "EUR-USD"). */
+export async function getFxPrice(ticker) {
+    return getPrice(ticker, 'fx');
+}
+/** Convenience: commodity lookup (e.g. "XAU-USD" for gold). */
+export async function getCommodityPrice(ticker) {
+    return getPrice(ticker, 'commodity');
 }
-export async function getPrice(ticker) {
-    const id = resolveId(ticker);
-    return cached(`price:${id}`, TTL_PRICE, async () => {
-        const raw = await geckofetch(`/simple/price?ids=${id}&vs_currencies=usd&include_24hr_change=true&include_market_cap=true&include_24hr_vol=true`);
-        if (typeof raw === "string")
-            return raw;
-        const d = raw[id];
-        if (!d)
-            return `no data for ${ticker}`;
-        return {
-            price: d.usd,
-            change24h: d.usd_24h_change,
-            volume24h: d.usd_24h_vol,
-            marketCap: d.usd_market_cap,
-        };
-    });
+/** Convenience: stock lookup (e.g. "AAPL" on market "us"). */
+export async function getStockPrice(ticker, market) {
+    return getPrice(ticker, 'stock', market);
 }
 export async function getOHLCV(ticker, days = 30) {
-    const id = resolveId(ticker);
-    return cached(`ohlcv:${id}:${days}`, TTL_OHLCV, async () => {
-        const raw = await geckofetch(`/coins/${id}/market_chart?vs_currency=usd&days=${days}&interval=daily`);
-        if (typeof raw === "string")
-            return raw;
-        const prices = raw.prices;
-        return {
-            timestamps: prices.map(p => p[0]),
-            closes: prices.map(p => p[1]),
-        };
-    });
+    const result = await runFetcher(getProvider('ohlcv'), { ticker, days });
+    if (isProviderError(result))
+        return result.message;
+    return { closes: result.closes, timestamps: result.timestamps };
 }
 export async function getTrending() {
-    return cached("trending", TTL_TRENDING, async () => {
-        const raw = await geckofetch("/search/trending");
-        if (typeof raw === "string")
-            return raw;
-        const coins = raw.coins;
-        return coins.map(c => ({
-            id: c.item.id,
-            name: c.item.name,
-            symbol: c.item.symbol,
-            marketCapRank: c.item.market_cap_rank,
-        }));
-    });
+    const result = await runFetcher(getProvider('trending'), {});
+    if (isProviderError(result))
+        return result.message;
+    return result.map(c => ({
+        id: c.providerId,
+        name: c.name,
+        symbol: c.symbol,
+        marketCapRank: c.marketCapRank,
+    }));
 }
 export async function getMarketOverview() {
-    return cached("markets", TTL_TRENDING, async () => {
-        const raw = await geckofetch("/coins/markets?vs_currency=usd&order=market_cap_desc&per_page=20&page=1");
-        if (typeof raw === "string")
-            return raw;
-        return raw.map(c => ({
-            id: c.id,
-            symbol: c.symbol,
-            name: c.name,
-            price: c.current_price,
-            change24h: c.price_change_percentage_24h,
-            marketCap: c.market_cap,
-            volume24h: c.total_volume,
-        }));
-    });
+    const result = await runFetcher(getProvider('markets'), { limit: 20 });
+    if (isProviderError(result))
+        return result.message;
+    return result.map(c => ({
+        id: c.providerId,
+        symbol: c.ticker.toLowerCase(),
+        name: c.name,
+        price: c.priceUsd,
+        change24h: c.change24hPct,
+        marketCap: c.marketCapUsd,
+        volume24h: c.volume24hUsd,
+    }));
 }

package/dist/trading/providers/blockrun/client.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Shared BlockRun Gateway HTTP client + short-TTL cache.
+ *
+ * Used by every BlockRun-backed fetcher (price, future OHLCV, etc). Mirrors
+ * the shape of `coingecko/client.ts` so the two providers feel the same to
+ * callers and tests.
+ *
+ * Chain-aware: base URL follows `loadChain()` — Base mainnet users hit
+ * `blockrun.ai`, Solana users hit `sol.blockrun.ai`. Trading data endpoints
+ * live under `/v1/*` (not `/api/v1`, which is the LLM proxy surface).
+ *
+ * PR 1 scope: free endpoints only (crypto / fx / commodity price). Paid
+ * stocks endpoints (`/v1/stocks/{market}/price/{symbol}`) arrive in PR 2
+ * together with the x402 signing wrapper.
+ */
+import type { ProviderError } from '../standard-models.js';
+export declare function cached<T>(key: string, ttlMs: number, fn: () => Promise<T>): Promise<T>;
+/** For tests: wipe every cached entry. */
+export declare function clearCache(): void;
+/**
+ * Fire-and-parse: GET a BlockRun Gateway REST endpoint. Returns parsed JSON
+ * or a structured ProviderError — never throws. Records latency + outcome
+ * to the telemetry singleton so the Panel Markets page can show live health.
+ */
+export declare function blockrunGet(path: string, opts?: {
+    endpoint: string;
+    paid?: boolean;
+    costUsd?: number;
+}): Promise<unknown | ProviderError>;
+/**
+ * GET a paid BlockRun Gateway endpoint with automatic x402 signing.
+ * Returns parsed JSON or a structured ProviderError. Never throws.
+ */
+export declare function blockrunGetPaid(path: string, opts: {
+    endpoint: string;
+    costUsd: number;
+}): Promise<unknown | ProviderError>;
+/**
+ * Pyth-style symbols always end in `-USD`. Agents may pass `BTC` meaning
+ * `BTC-USD`; normalize so both shapes work.
+ */
+export declare function normalizePythSymbol(ticker: string): string;
+/** TTLs chosen to match CoinGecko's; Pyth pushes more often but we don't
+ *  need sub-minute freshness for Franklin's agent cadence. */
+export declare const TTL: {
+    readonly price: number;
+    readonly ohlcv: number;
+};