@blockrun/franklin 3.8.8 → 3.8.10

package/dist/trading/providers/coingecko/client.js

@@ -0,0 +1,87 @@
+/**
+ * Shared CoinGecko HTTP client + short-TTL cache.
+ *
+ * Carved out of the original `src/trading/data.ts` so every CoinGecko
+ * fetcher (price, ohlcv, trending, markets) shares the same rate-limit
+ * cooldown, user-agent, timeout, and in-memory cache.
+ */
+import { recordFetch } from '../telemetry.js';
+const BASE = 'https://api.coingecko.com/api/v3';
+const UA = 'franklin/3.8.9 (trading)';
+const TIMEOUT_MS = 10_000;
+// Ticker → CoinGecko slug. Not exhaustive; unknown tickers fall through to
+// lowercase and let CoinGecko either accept the slug or 404.
+export const TICKER_TO_ID = {
+    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',
+};
+export function resolveProviderId(ticker) {
+    // Accept both "BTC" and "BTC-USD" — Pyth-style callers may pass the pair
+    // form even when the registry routes them to CoinGecko.
+    const normalized = ticker.toUpperCase().replace(/-USD$/, '').replace(/USDT?$/, '');
+    return TICKER_TO_ID[normalized] ?? TICKER_TO_ID[ticker.toUpperCase()] ?? normalized.toLowerCase();
+}
+const cache = new Map();
+export async function cached(key, ttlMs, fn) {
+    const hit = cache.get(key);
+    if (hit && hit.expiry > Date.now())
+        return hit.data;
+    const data = await fn();
+    cache.set(key, { data, expiry: Date.now() + ttlMs });
+    return data;
+}
+/** For tests: wipe every cached entry. */
+export function clearCache() {
+    cache.clear();
+}
+export async function coingeckoGet(path) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
+    const endpoint = path.split('?')[0];
+    const startedAt = Date.now();
+    try {
+        const res = await fetch(`${BASE}${path}`, {
+            headers: { 'User-Agent': UA },
+            signal: ctrl.signal,
+        });
+        const latencyMs = Date.now() - startedAt;
+        if (res.status === 429) {
+            recordFetch({ provider: 'coingecko', endpoint, ok: false, latencyMs });
+            return { kind: 'rate-limited', message: 'CoinGecko rate-limited this request (HTTP 429). Retry in a minute.' };
+        }
+        if (res.status === 404) {
+            recordFetch({ provider: 'coingecko', endpoint, ok: false, latencyMs });
+            return { kind: 'not-found', message: `CoinGecko returned 404 for path ${path}` };
+        }
+        if (!res.ok) {
+            recordFetch({ provider: 'coingecko', endpoint, ok: false, latencyMs });
+            return { kind: 'upstream-error', message: `CoinGecko HTTP ${res.status}` };
+        }
+        recordFetch({ provider: 'coingecko', endpoint, ok: true, latencyMs });
+        return await res.json();
+    }
+    catch (e) {
+        const latencyMs = Date.now() - startedAt;
+        if (e instanceof DOMException && e.name === 'AbortError') {
+            recordFetch({ provider: 'coingecko', endpoint, ok: false, latencyMs });
+            return { kind: 'timeout', message: `CoinGecko request timed out after ${TIMEOUT_MS}ms` };
+        }
+        recordFetch({ provider: 'coingecko', endpoint, ok: false, latencyMs });
+        return { kind: 'unknown', message: String(e) };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+// TTLs for cache reuse across fetchers.
+export const TTL = {
+    price: 5 * 60_000,
+    ohlcv: 60 * 60_000,
+    trending: 15 * 60_000,
+    markets: 15 * 60_000,
+};

package/dist/trading/providers/coingecko/markets.d.ts

@@ -0,0 +1,3 @@
+import type { Fetcher } from '../fetcher.js';
+import type { MarketCoinData, MarketOverviewQueryParams } from '../standard-models.js';
+export declare const coingeckoMarketsFetcher: Fetcher<MarketOverviewQueryParams, MarketCoinData[]>;

package/dist/trading/providers/coingecko/markets.js

@@ -0,0 +1,25 @@
+import { cached, coingeckoGet, TTL } from './client.js';
+export const coingeckoMarketsFetcher = {
+    providerName: 'coingecko',
+    transformQuery(input) {
+        const limit = Math.max(1, Math.min(100, Math.round(Number(input.limit ?? 20))));
+        return { limit };
+    },
+    async fetchData(query) {
+        return cached(`markets:${query.limit}`, TTL.markets, async () => coingeckoGet(`/coins/markets?vs_currency=usd&order=market_cap_desc&per_page=${query.limit}&page=1`));
+    },
+    transformData(raw, _query) {
+        if (!Array.isArray(raw)) {
+            return { kind: 'upstream-error', message: 'CoinGecko /coins/markets returned unexpected shape' };
+        }
+        return raw.map(c => ({
+            providerId: c.id,
+            ticker: c.symbol.toUpperCase(),
+            name: c.name,
+            priceUsd: c.current_price,
+            change24hPct: c.price_change_percentage_24h,
+            marketCapUsd: c.market_cap,
+            volume24hUsd: c.total_volume,
+        }));
+    },
+};

package/dist/trading/providers/coingecko/ohlcv.d.ts

@@ -0,0 +1,3 @@
+import type { Fetcher } from '../fetcher.js';
+import type { OHLCVData, OHLCVQueryParams } from '../standard-models.js';
+export declare const coingeckoOHLCVFetcher: Fetcher<OHLCVQueryParams, OHLCVData>;

package/dist/trading/providers/coingecko/ohlcv.js

@@ -0,0 +1,29 @@
+import { cached, coingeckoGet, resolveProviderId, TTL } from './client.js';
+export const coingeckoOHLCVFetcher = {
+    providerName: 'coingecko',
+    transformQuery(input) {
+        const ticker = String(input.ticker ?? '').trim().toUpperCase();
+        if (!ticker)
+            throw new Error('OHLCVQueryParams.ticker is required');
+        const days = Math.max(1, Math.min(365, Math.round(Number(input.days ?? 30))));
+        return { ticker, days };
+    },
+    async fetchData(query) {
+        const id = resolveProviderId(query.ticker);
+        return cached(`ohlcv:${id}:${query.days}`, TTL.ohlcv, async () => {
+            return coingeckoGet(`/coins/${id}/market_chart?vs_currency=usd&days=${query.days}&interval=daily`);
+        });
+    },
+    transformData(raw, query) {
+        const payload = raw;
+        const prices = payload?.prices;
+        if (!Array.isArray(prices) || prices.length === 0) {
+            return { kind: 'not-found', message: `No OHLCV data for ${query.ticker} (${query.days}d)` };
+        }
+        return {
+            ticker: query.ticker,
+            timestamps: prices.map(p => p[0]),
+            closes: prices.map(p => p[1]),
+        };
+    },
+};

package/dist/trading/providers/coingecko/price.d.ts

@@ -0,0 +1,11 @@
+/**
+ * CoinGecko implementation of Fetcher<PriceQueryParams, PriceData>.
+ *
+ * Transforms: uppercase ticker → CoinGecko slug lookup.
+ * Fetches: /simple/price with 24h change/cap/volume flags.
+ * Coerces: the nested `{ [id]: { usd: ..., usd_24h_change: ... } }`
+ *          response into the standard PriceData shape.
+ */
+import type { Fetcher } from '../fetcher.js';
+import type { PriceData, PriceQueryParams } from '../standard-models.js';
+export declare const coingeckoPriceFetcher: Fetcher<PriceQueryParams, PriceData>;

package/dist/trading/providers/coingecko/price.js

@@ -0,0 +1,41 @@
+/**
+ * CoinGecko implementation of Fetcher<PriceQueryParams, PriceData>.
+ *
+ * Transforms: uppercase ticker → CoinGecko slug lookup.
+ * Fetches: /simple/price with 24h change/cap/volume flags.
+ * Coerces: the nested `{ [id]: { usd: ..., usd_24h_change: ... } }`
+ *          response into the standard PriceData shape.
+ */
+import { cached, coingeckoGet, resolveProviderId, TTL } from './client.js';
+export const coingeckoPriceFetcher = {
+    providerName: 'coingecko',
+    transformQuery(input) {
+        const ticker = String(input.ticker ?? '').trim().toUpperCase();
+        if (!ticker) {
+            throw new Error('PriceQueryParams.ticker is required');
+        }
+        return { ticker };
+    },
+    async fetchData(query) {
+        const id = resolveProviderId(query.ticker);
+        return cached(`price:${id}`, TTL.price, async () => {
+            return coingeckoGet(`/simple/price?ids=${id}` +
+                `&vs_currencies=usd&include_24hr_change=true` +
+                `&include_market_cap=true&include_24hr_vol=true`);
+        });
+    },
+    transformData(raw, query) {
+        const id = resolveProviderId(query.ticker);
+        const entry = raw[id];
+        if (!entry) {
+            return { kind: 'not-found', message: `No CoinGecko data for ${query.ticker}` };
+        }
+        return {
+            ticker: query.ticker,
+            priceUsd: entry.usd,
+            change24hPct: entry.usd_24h_change,
+            volume24hUsd: entry.usd_24h_vol,
+            marketCapUsd: entry.usd_market_cap,
+        };
+    },
+};

package/dist/trading/providers/coingecko/trending.d.ts

@@ -0,0 +1,3 @@
+import type { Fetcher } from '../fetcher.js';
+import type { TrendingCoinData, TrendingQueryParams } from '../standard-models.js';
+export declare const coingeckoTrendingFetcher: Fetcher<TrendingQueryParams, TrendingCoinData[]>;

package/dist/trading/providers/coingecko/trending.js

@@ -0,0 +1,22 @@
+import { cached, coingeckoGet, TTL } from './client.js';
+export const coingeckoTrendingFetcher = {
+    providerName: 'coingecko',
+    transformQuery(_input) {
+        return {};
+    },
+    async fetchData(_query) {
+        return cached('trending', TTL.trending, async () => coingeckoGet('/search/trending'));
+    },
+    transformData(raw, _query) {
+        const payload = raw;
+        if (!payload || !Array.isArray(payload.coins)) {
+            return { kind: 'upstream-error', message: 'CoinGecko /search/trending returned unexpected shape' };
+        }
+        return payload.coins.map(c => ({
+            providerId: c.item.id,
+            name: c.item.name,
+            symbol: c.item.symbol,
+            marketCapRank: c.item.market_cap_rank,
+        }));
+    },
+};

package/dist/trading/providers/fetcher.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Fetcher<Query, Data> — the three-step Transform/Extract/Transform (TET)
+ * contract every trading data provider implements.
+ *
+ * Named after OpenBB's provider abstraction but reduced to the shape that
+ * actually pays rent in a single-language TypeScript codebase:
+ *
+ *   1. `transformQuery(input)` — normalize caller input (ticker casing,
+ *      default values, clamping) into the provider's expected query.
+ *   2. `fetchData(query)` — hit the provider's API, return raw payload or a
+ *      ProviderError.
+ *   3. `transformData(raw, query)` — coerce the raw payload into the
+ *      standard data type the rest of the codebase consumes.
+ *
+ * Keeping these three steps separate makes providers testable in isolation:
+ * you can feed a canned raw payload into `transformData` without mocking
+ * HTTP. It also keeps the provider code free of formatting concerns —
+ * rendering is views' job, not fetchers'.
+ */
+import type { ProviderError } from './standard-models.js';
+export interface Fetcher<Query, Data, Raw = unknown> {
+    /** Human-readable provider id — "coingecko", "binance", etc. */
+    readonly providerName: string;
+    /** Lowercase the ticker, clamp limits, fill defaults. */
+    transformQuery(input: Partial<Query>): Query;
+    /** Hit the upstream API. Must not throw — return ProviderError on failure. */
+    fetchData(query: Query): Promise<Raw | ProviderError>;
+    /** Coerce raw → standard data shape. Returns ProviderError if the shape
+     *  doesn't map (e.g., provider returned an empty object for a ticker). */
+    transformData(raw: Raw, query: Query): Data | ProviderError;
+    /**
+     * Convenience: end-to-end run. Default implementation composes the three
+     * steps; providers can override when a single-step optimization exists.
+     */
+    run?(input: Partial<Query>): Promise<Data | ProviderError>;
+}
+/**
+ * Helper: run a fetcher end-to-end with the default composition. Providers
+ * that want caching, retries, or parallel fan-out can skip this and write
+ * their own `run`. Kept as a plain function so callers don't depend on
+ * object-oriented glue.
+ */
+export declare function runFetcher<Q, D, R>(fetcher: Fetcher<Q, D, R>, input: Partial<Q>): Promise<D | ProviderError>;

package/dist/trading/providers/fetcher.js

@@ -0,0 +1,45 @@
+/**
+ * Fetcher<Query, Data> — the three-step Transform/Extract/Transform (TET)
+ * contract every trading data provider implements.
+ *
+ * Named after OpenBB's provider abstraction but reduced to the shape that
+ * actually pays rent in a single-language TypeScript codebase:
+ *
+ *   1. `transformQuery(input)` — normalize caller input (ticker casing,
+ *      default values, clamping) into the provider's expected query.
+ *   2. `fetchData(query)` — hit the provider's API, return raw payload or a
+ *      ProviderError.
+ *   3. `transformData(raw, query)` — coerce the raw payload into the
+ *      standard data type the rest of the codebase consumes.
+ *
+ * Keeping these three steps separate makes providers testable in isolation:
+ * you can feed a canned raw payload into `transformData` without mocking
+ * HTTP. It also keeps the provider code free of formatting concerns —
+ * rendering is views' job, not fetchers'.
+ */
+/**
+ * Helper: run a fetcher end-to-end with the default composition. Providers
+ * that want caching, retries, or parallel fan-out can skip this and write
+ * their own `run`. Kept as a plain function so callers don't depend on
+ * object-oriented glue.
+ */
+export async function runFetcher(fetcher, input) {
+    try {
+        if (fetcher.run)
+            return fetcher.run(input);
+        const query = fetcher.transformQuery(input);
+        const raw = await fetcher.fetchData(query);
+        if (isProviderErrorLike(raw))
+            return raw;
+        return fetcher.transformData(raw, query);
+    }
+    catch (err) {
+        return {
+            kind: 'unknown',
+            message: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+function isProviderErrorLike(v) {
+    return typeof v === 'object' && v !== null && 'kind' in v && 'message' in v;
+}

package/dist/trading/providers/registry.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Provider registry.
+ *
+ * Single source of truth for which Fetcher implementation a given standard
+ * query should route to. One named slot per data kind — plus a keyed map
+ * for `price` so we can route per asset class (crypto → CoinGecko free tier,
+ * fx/commodity/stock → BlockRun Gateway / Pyth) without the call sites
+ * knowing which provider is active.
+ *
+ * Design note: this is intentionally not a dependency-injection framework.
+ * Tests that need to stub a provider should call `setProvider*()` before
+ * acting and reset with `resetProviders()` in a teardown. No magic.
+ */
+import type { Fetcher } from './fetcher.js';
+import type { AssetClass, MarketCoinData, MarketOverviewQueryParams, OHLCVData, OHLCVQueryParams, PriceData, PriceQueryParams, TrendingCoinData, TrendingQueryParams } from './standard-models.js';
+export type PriceFetcher = Fetcher<PriceQueryParams, PriceData>;
+export interface TradingProviders {
+    /** Per-asset-class price fetcher. `getPriceProvider(assetClass)` reads this. */
+    price: Record<AssetClass, PriceFetcher>;
+    ohlcv: Fetcher<OHLCVQueryParams, OHLCVData>;
+    trending: Fetcher<TrendingQueryParams, TrendingCoinData[]>;
+    markets: Fetcher<MarketOverviewQueryParams, MarketCoinData[]>;
+}
+/** Read the active fetcher for a singleton data kind (not price). */
+export declare function getProvider<K extends Exclude<keyof TradingProviders, 'price'>>(kind: K): TradingProviders[K];
+/** Read the active price fetcher for a given asset class. Defaults to crypto. */
+export declare function getPriceProvider(assetClass?: AssetClass): PriceFetcher;
+/** Replace one singleton fetcher. */
+export declare function setProvider<K extends Exclude<keyof TradingProviders, 'price'>>(kind: K, fetcher: TradingProviders[K]): void;
+/** Replace one asset-class price fetcher. */
+export declare function setPriceProvider(assetClass: AssetClass, fetcher: PriceFetcher): void;
+/** Restore the default wiring — primarily for test isolation. */
+export declare function resetProviders(): void;
+/**
+ * Describe the active wiring for introspection (Panel Markets page, debug).
+ * Returns a per-asset-class listing plus the singleton kinds.
+ */
+export interface ProviderWiringRow {
+    kind: string;
+    assetClass?: AssetClass;
+    provider: string;
+    endpoint: string;
+    paid: boolean;
+}
+export declare function describeWiring(): ProviderWiringRow[];

package/dist/trading/providers/registry.js

@@ -0,0 +1,82 @@
+/**
+ * Provider registry.
+ *
+ * Single source of truth for which Fetcher implementation a given standard
+ * query should route to. One named slot per data kind — plus a keyed map
+ * for `price` so we can route per asset class (crypto → CoinGecko free tier,
+ * fx/commodity/stock → BlockRun Gateway / Pyth) without the call sites
+ * knowing which provider is active.
+ *
+ * Design note: this is intentionally not a dependency-injection framework.
+ * Tests that need to stub a provider should call `setProvider*()` before
+ * acting and reset with `resetProviders()` in a teardown. No magic.
+ */
+import { coingeckoPriceFetcher } from './coingecko/price.js';
+import { coingeckoOHLCVFetcher } from './coingecko/ohlcv.js';
+import { coingeckoTrendingFetcher } from './coingecko/trending.js';
+import { coingeckoMarketsFetcher } from './coingecko/markets.js';
+import { blockrunPriceFetcher } from './blockrun/price.js';
+const DEFAULT_PROVIDERS = {
+    price: {
+        crypto: coingeckoPriceFetcher,
+        fx: blockrunPriceFetcher,
+        commodity: blockrunPriceFetcher,
+        stock: blockrunPriceFetcher,
+    },
+    ohlcv: coingeckoOHLCVFetcher,
+    trending: coingeckoTrendingFetcher,
+    markets: coingeckoMarketsFetcher,
+};
+let current = {
+    ...DEFAULT_PROVIDERS,
+    price: { ...DEFAULT_PROVIDERS.price },
+};
+/** Read the active fetcher for a singleton data kind (not price). */
+export function getProvider(kind) {
+    return current[kind];
+}
+/** Read the active price fetcher for a given asset class. Defaults to crypto. */
+export function getPriceProvider(assetClass = 'crypto') {
+    return current.price[assetClass];
+}
+/** Replace one singleton fetcher. */
+export function setProvider(kind, fetcher) {
+    current[kind] = fetcher;
+}
+/** Replace one asset-class price fetcher. */
+export function setPriceProvider(assetClass, fetcher) {
+    current.price[assetClass] = fetcher;
+}
+/** Restore the default wiring — primarily for test isolation. */
+export function resetProviders() {
+    current = {
+        ...DEFAULT_PROVIDERS,
+        price: { ...DEFAULT_PROVIDERS.price },
+    };
+}
+export function describeWiring() {
+    const rows = [];
+    const priceEndpoints = {
+        crypto: { endpoint: 'coingecko /simple/price · blockrun /api/v1/crypto/price', paid: false },
+        fx: { endpoint: '/api/v1/fx/price', paid: false },
+        commodity: { endpoint: '/api/v1/commodity/price', paid: false },
+        stock: { endpoint: '/api/v1/stocks/{market}/price', paid: true },
+    };
+    for (const ac of ['crypto', 'fx', 'commodity', 'stock']) {
+        const f = current.price[ac];
+        const meta = priceEndpoints[ac];
+        rows.push({
+            kind: 'price',
+            assetClass: ac,
+            provider: f.providerName,
+            endpoint: ac === 'crypto' && f.providerName === 'coingecko'
+                ? 'coingecko /simple/price'
+                : meta.endpoint.split(' · ').pop() || meta.endpoint,
+            paid: meta.paid,
+        });
+    }
+    rows.push({ kind: 'ohlcv', provider: current.ohlcv.providerName, endpoint: '/coins/{id}/market_chart', paid: false });
+    rows.push({ kind: 'trending', provider: current.trending.providerName, endpoint: '/search/trending', paid: false });
+    rows.push({ kind: 'markets', provider: current.markets.providerName, endpoint: '/coins/markets', paid: false });
+    return rows;
+}

package/dist/trading/providers/standard-models.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Provider-agnostic trading data contracts.
+ *
+ * Every trading data source (CoinGecko today, Binance/CoinMarketCap/etc.
+ * tomorrow) must produce these types. Downstream code — the trading engine,
+ * the `trading-market` tool, the `trading-signal` tool — depends on these
+ * types, not on provider-specific response shapes. That's the whole point:
+ * swapping providers becomes a registry change, not a codebase change.
+ *
+ * Pattern: standard query params + standard data shape, both serializable,
+ * both strictly typed. Providers are free to accept extra fields in their
+ * own query shapes (time zone, cache bust, etc.) but their output must
+ * coerce to the standard data type before returning.
+ */
+/**
+ * Asset classes Franklin recognizes. Crypto is today; the rest unlock the
+ * moment a provider with non-crypto coverage (BlockRun Gateway / Pyth) is
+ * wired into the registry. Fetchers inspect this to pick the correct
+ * upstream endpoint.
+ */
+export type AssetClass = 'crypto' | 'fx' | 'commodity' | 'stock';
+/**
+ * Stock exchange market codes BlockRun Gateway understands. Only meaningful
+ * when `assetClass === 'stock'`; ignored otherwise.
+ */
+export type MarketCode = 'us' | 'hk' | 'jp' | 'kr' | 'gb' | 'de' | 'fr' | 'nl' | 'ie' | 'lu' | 'cn' | 'ca';
+/** Common to every query: a ticker the provider will resolve itself. */
+export interface PriceQueryParams {
+    ticker: string;
+    /** Defaults to 'crypto' so existing callers keep working without churn. */
+    assetClass?: AssetClass;
+    /** Required when assetClass === 'stock'. Ignored otherwise. */
+    market?: MarketCode;
+}
+export interface PriceData {
+    ticker: string;
+    priceUsd: number;
+    change24hPct: number;
+    volume24hUsd: number;
+    marketCapUsd: number;
+}
+export interface OHLCVQueryParams {
+    ticker: string;
+    /** Number of calendar days of history, typically 1-365. */
+    days: number;
+}
+export interface OHLCVData {
+    ticker: string;
+    /** Epoch-ms timestamps aligned with closes. */
+    timestamps: number[];
+    /** Daily closing prices in USD. */
+    closes: number[];
+}
+export interface TrendingQueryParams {
+    _?: never;
+}
+export interface TrendingCoinData {
+    providerId: string;
+    symbol: string;
+    name: string;
+    marketCapRank: number | null;
+}
+export interface MarketOverviewQueryParams {
+    /** Top N by market cap. Providers may cap this internally. */
+    limit: number;
+}
+export interface MarketCoinData {
+    providerId: string;
+    ticker: string;
+    name: string;
+    priceUsd: number;
+    change24hPct: number;
+    marketCapUsd: number;
+    volume24hUsd: number;
+}
+/**
+ * Error convention: providers return a `ProviderError` (plain object) rather
+ * than throwing, so the caller can render it inline without try/catch at
+ * every tool handler. This mirrors the legacy `string | PriceData` return
+ * type but is structured — the `kind` field lets the UI color-code without
+ * string parsing.
+ */
+export interface ProviderError {
+    kind: 'rate-limited' | 'timeout' | 'not-found' | 'upstream-error' | 'unknown';
+    message: string;
+    /**
+     * Optional provider- or endpoint-specific subcode. Populated when the
+     * caller can take a different action than a generic error allows
+     * (e.g. "fund your wallet" vs "retry later"). Consumers should render
+     * `message` when `code` is absent.
+     */
+    code?: 'insufficient-funds' | 'budget-exceeded' | 'schema-mismatch' | 'unsupported-asset-class' | 'missing-market-code';
+}
+export declare function isProviderError(v: unknown): v is ProviderError;

package/dist/trading/providers/standard-models.js

@@ -0,0 +1,21 @@
+/**
+ * Provider-agnostic trading data contracts.
+ *
+ * Every trading data source (CoinGecko today, Binance/CoinMarketCap/etc.
+ * tomorrow) must produce these types. Downstream code — the trading engine,
+ * the `trading-market` tool, the `trading-signal` tool — depends on these
+ * types, not on provider-specific response shapes. That's the whole point:
+ * swapping providers becomes a registry change, not a codebase change.
+ *
+ * Pattern: standard query params + standard data shape, both serializable,
+ * both strictly typed. Providers are free to accept extra fields in their
+ * own query shapes (time zone, cache bust, etc.) but their output must
+ * coerce to the standard data type before returning.
+ */
+export function isProviderError(v) {
+    return (typeof v === 'object' &&
+        v !== null &&
+        'kind' in v &&
+        'message' in v &&
+        typeof v.message === 'string');
+}

package/dist/trading/providers/telemetry.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Provider-layer telemetry.
+ *
+ * Records every fetcher call so the Panel Markets page can show live health
+ * ("• CoinGecko OK", "• BlockRun OK"), today's call count, today's spend,
+ * and a p50 latency estimate. Entirely in-memory — dies with the process
+ * and re-hydrates from the on-disk wallet/stats files if we ever care to
+ * persist (we don't yet).
+ *
+ * Tiny by design: zero deps, no background timers, no DB. Callers push a
+ * single record per fetch; the Panel pulls a snapshot on demand.
+ */
+type ProviderName = 'coingecko' | 'blockrun';
+interface FetchRecord {
+    provider: ProviderName;
+    endpoint: string;
+    ok: boolean;
+    latencyMs: number;
+    costUsd?: number;
+    ts: number;
+}
+interface PaidCallRow {
+    endpoint: string;
+    costUsd: number;
+    ts: number;
+}
+export declare function recordFetch(evt: Omit<FetchRecord, 'ts'>): void;
+export interface ProviderSnapshot {
+    name: ProviderName;
+    calls: number;
+    ok: number;
+    failures: number;
+    p50LatencyMs: number | null;
+    lastOkAt: number | null;
+    lastErrorAt: number | null;
+    spendUsdToday: number;
+    status: 'ok' | 'degraded' | 'cold';
+}
+export interface TelemetrySnapshot {
+    providers: ProviderSnapshot[];
+    totals: {
+        callsToday: number;
+        spendUsdToday: number;
+        p50LatencyMs: number | null;
+    };
+    recentPaidCalls: PaidCallRow[];
+}
+export declare function snapshot(): TelemetrySnapshot;
+/** Test helper: reset all counters. Do not call in production code paths. */
+export declare function resetTelemetry(): void;
+export {};