@blockrun/franklin 3.8.8 → 3.8.10

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;
+};

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

@@ -0,0 +1,253 @@
+/**
+ * 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 { USER_AGENT, loadChain } from '../../../config.js';
+import { recordFetch } from '../telemetry.js';
+import { getOrCreateWallet, getOrCreateSolanaWallet, createPaymentPayload, createSolanaPaymentPayload, parsePaymentRequired, extractPaymentDetails, solanaKeyToBytes, SOLANA_NETWORK, } from '@blockrun/llm';
+const TIMEOUT_MS = 10_000;
+function baseUrl() {
+    // `loadChain()` dispatches on env / ~/.blockrun/payment-chain. We match it
+    // every call so mid-session chain switches take effect without restart.
+    return loadChain() === 'solana' ? 'https://sol.blockrun.ai' : 'https://blockrun.ai';
+}
+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();
+}
+/**
+ * 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 async function blockrunGet(path, opts = { endpoint: path }) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
+    const url = `${baseUrl()}${path}`;
+    const startedAt = Date.now();
+    try {
+        const res = await fetch(url, {
+            headers: { 'User-Agent': USER_AGENT, Accept: 'application/json' },
+            signal: ctrl.signal,
+        });
+        const latencyMs = Date.now() - startedAt;
+        if (res.status === 429) {
+            recordFetch({ provider: 'blockrun', endpoint: opts.endpoint, ok: false, latencyMs });
+            return {
+                kind: 'rate-limited',
+                message: `BlockRun Gateway rate-limited this request (HTTP 429). Retry shortly.`,
+            };
+        }
+        if (res.status === 404) {
+            recordFetch({ provider: 'blockrun', endpoint: opts.endpoint, ok: false, latencyMs });
+            return { kind: 'not-found', message: `BlockRun Gateway 404 for ${path}` };
+        }
+        if (res.status === 402) {
+            // Free-path client should never see a 402. If the Gateway starts
+            // charging for an endpoint that was free, surface an actionable
+            // error and let the caller migrate to `blockrunGetPaid`.
+            recordFetch({ provider: 'blockrun', endpoint: opts.endpoint, ok: false, latencyMs });
+            return {
+                kind: 'upstream-error',
+                code: 'insufficient-funds',
+                message: `Gateway unexpectedly requires payment for ${path}. Move this endpoint to blockrunGetPaid.`,
+            };
+        }
+        if (!res.ok) {
+            recordFetch({ provider: 'blockrun', endpoint: opts.endpoint, ok: false, latencyMs });
+            return { kind: 'upstream-error', message: `BlockRun Gateway HTTP ${res.status}` };
+        }
+        const data = await res.json();
+        recordFetch({
+            provider: 'blockrun',
+            endpoint: opts.endpoint,
+            ok: true,
+            latencyMs,
+            costUsd: opts.paid ? opts.costUsd ?? 0 : 0,
+        });
+        return data;
+    }
+    catch (e) {
+        const latencyMs = Date.now() - startedAt;
+        if (e instanceof DOMException && e.name === 'AbortError') {
+            recordFetch({ provider: 'blockrun', endpoint: opts.endpoint, ok: false, latencyMs });
+            return { kind: 'timeout', message: `BlockRun Gateway timed out after ${TIMEOUT_MS}ms` };
+        }
+        recordFetch({ provider: 'blockrun', endpoint: opts.endpoint, ok: false, latencyMs });
+        return { kind: 'unknown', message: String(e) };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+// ─── x402 paid GET ──────────────────────────────────────────────────────
+//
+// Mirrors the POST payment flow in `src/tools/exa.ts` but for GET requests
+// against Pyth paid endpoints (stocks today; historical OHLCV tomorrow).
+// Lazy-loads the wallet on first 402 so free endpoints never touch the
+// wallet module.
+//
+// No budget gate, no pre-flight check, no soft refusal — Franklin's whole
+// identity is "agent with a wallet that spends USDC for real work". $0.001
+// per stock quote is not a category that warrants a permission prompt.
+async function extractPaymentReq(response) {
+    let header = response.headers.get('payment-required');
+    if (!header) {
+        try {
+            const body = (await response.json());
+            if (body.x402 || body.accepts)
+                header = btoa(JSON.stringify(body));
+        }
+        catch { /* ignore */ }
+    }
+    return header;
+}
+async function signGatewayPayment(response, chain, endpoint) {
+    try {
+        const paymentHeader = await extractPaymentReq(response);
+        if (!paymentHeader)
+            return null;
+        if (chain === 'solana') {
+            const wallet = await getOrCreateSolanaWallet();
+            const paymentRequired = parsePaymentRequired(paymentHeader);
+            const details = extractPaymentDetails(paymentRequired, SOLANA_NETWORK);
+            const secretBytes = await solanaKeyToBytes(wallet.privateKey);
+            const feePayer = details.extra?.feePayer || details.recipient;
+            const payload = await createSolanaPaymentPayload(secretBytes, wallet.address, details.recipient, details.amount, feePayer, {
+                resourceUrl: details.resource?.url || endpoint,
+                resourceDescription: details.resource?.description || 'Franklin trading data',
+                maxTimeoutSeconds: details.maxTimeoutSeconds || 60,
+                extra: details.extra,
+            });
+            return { 'PAYMENT-SIGNATURE': payload };
+        }
+        const wallet = getOrCreateWallet();
+        const paymentRequired = parsePaymentRequired(paymentHeader);
+        const details = extractPaymentDetails(paymentRequired);
+        const payload = await createPaymentPayload(wallet.privateKey, wallet.address, details.recipient, details.amount, details.network || 'eip155:8453', {
+            resourceUrl: details.resource?.url || endpoint,
+            resourceDescription: details.resource?.description || 'Franklin trading data',
+            maxTimeoutSeconds: details.maxTimeoutSeconds || 60,
+            extra: details.extra,
+        });
+        return { 'PAYMENT-SIGNATURE': payload };
+    }
+    catch (err) {
+        // Bubble a typed error up so the caller can turn it into a
+        // ProviderError with code: 'insufficient-funds'.
+        throw new PaymentSignError(err.message);
+    }
+}
+class PaymentSignError extends Error {
+    constructor(message) { super(message); this.name = 'PaymentSignError'; }
+}
+/**
+ * GET a paid BlockRun Gateway endpoint with automatic x402 signing.
+ * Returns parsed JSON or a structured ProviderError. Never throws.
+ */
+export async function blockrunGetPaid(path, opts) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
+    const url = `${baseUrl()}${path}`;
+    const chain = loadChain();
+    const startedAt = Date.now();
+    const headers = {
+        'User-Agent': USER_AGENT,
+        Accept: 'application/json',
+    };
+    try {
+        let res = await fetch(url, { headers, signal: ctrl.signal });
+        if (res.status === 402) {
+            try {
+                const paid = await signGatewayPayment(res, chain, url);
+                if (!paid) {
+                    const latencyMs = Date.now() - startedAt;
+                    recordFetch({ provider: 'blockrun', endpoint: opts.endpoint, ok: false, latencyMs });
+                    return {
+                        kind: 'upstream-error',
+                        code: 'insufficient-funds',
+                        message: 'Gateway required payment but did not supply payment-required header. Fund your wallet: franklin wallet fund',
+                    };
+                }
+                res = await fetch(url, { headers: { ...headers, ...paid }, signal: ctrl.signal });
+            }
+            catch (e) {
+                const latencyMs = Date.now() - startedAt;
+                recordFetch({ provider: 'blockrun', endpoint: opts.endpoint, ok: false, latencyMs });
+                if (e instanceof PaymentSignError) {
+                    return {
+                        kind: 'upstream-error',
+                        code: 'insufficient-funds',
+                        message: `Payment failed: ${e.message}. Check wallet balance with "franklin wallet".`,
+                    };
+                }
+                throw e;
+            }
+        }
+        const latencyMs = Date.now() - startedAt;
+        if (res.status === 429) {
+            recordFetch({ provider: 'blockrun', endpoint: opts.endpoint, ok: false, latencyMs });
+            return { kind: 'rate-limited', message: 'BlockRun Gateway rate-limited this request. Retry shortly.' };
+        }
+        if (res.status === 404) {
+            recordFetch({ provider: 'blockrun', endpoint: opts.endpoint, ok: false, latencyMs });
+            return { kind: 'not-found', message: `BlockRun Gateway 404 for ${path}` };
+        }
+        if (!res.ok) {
+            recordFetch({ provider: 'blockrun', endpoint: opts.endpoint, ok: false, latencyMs });
+            return { kind: 'upstream-error', message: `BlockRun Gateway HTTP ${res.status}` };
+        }
+        const data = await res.json();
+        recordFetch({ provider: 'blockrun', endpoint: opts.endpoint, ok: true, latencyMs, costUsd: opts.costUsd });
+        return data;
+    }
+    catch (e) {
+        const latencyMs = Date.now() - startedAt;
+        recordFetch({ provider: 'blockrun', endpoint: opts.endpoint, ok: false, latencyMs });
+        if (e instanceof DOMException && e.name === 'AbortError') {
+            return { kind: 'timeout', message: `BlockRun Gateway timed out after ${TIMEOUT_MS}ms` };
+        }
+        return { kind: 'unknown', message: String(e) };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Pyth-style symbols always end in `-USD`. Agents may pass `BTC` meaning
+ * `BTC-USD`; normalize so both shapes work.
+ */
+export function normalizePythSymbol(ticker) {
+    const upper = ticker.trim().toUpperCase();
+    if (!upper)
+        return upper;
+    if (upper.includes('-'))
+        return upper;
+    return `${upper}-USD`;
+}
+/** TTLs chosen to match CoinGecko's; Pyth pushes more often but we don't
+ *  need sub-minute freshness for Franklin's agent cadence. */
+export const TTL = {
+    price: 5 * 60_000,
+    ohlcv: 60 * 60_000,
+};

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

@@ -0,0 +1,24 @@
+/**
+ * BlockRun Gateway price fetcher.
+ *
+ * One fetcher, many asset classes. Dispatches on `PriceQueryParams.assetClass`
+ * to the right Pyth-backed Gateway endpoint:
+ *
+ *   crypto     → /api/v1/crypto/price/{ticker}         free
+ *   fx         → /api/v1/fx/price/{ticker}             free
+ *   commodity  → /api/v1/commodity/price/{ticker}      free
+ *   stock      → /v1/stocks/{market}/price/{ticker} paid ($0.001 x402) — PR 2
+ *
+ * PR 1 scope: crypto / fx / commodity only. The stock branch returns a
+ * `ProviderError { code: 'insufficient-funds' }` until the x402 signing
+ * wrapper lands, so callers get a useful message instead of a wire-level
+ * 402.
+ *
+ * Response shape from Gateway: Pyth delivers `{ price, confidence, timestamp }`
+ * — no 24h change, no market cap, no volume. Legacy CoinGecko-shaped fields
+ * (`change24hPct`, `volume24hUsd`, `marketCapUsd`) come back as `NaN` for
+ * non-crypto classes; views treat NaN as "not applicable" and render a dash.
+ */
+import type { Fetcher } from '../fetcher.js';
+import type { PriceData, PriceQueryParams } from '../standard-models.js';
+export declare const blockrunPriceFetcher: Fetcher<PriceQueryParams, PriceData>;

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

@@ -0,0 +1,110 @@
+/**
+ * BlockRun Gateway price fetcher.
+ *
+ * One fetcher, many asset classes. Dispatches on `PriceQueryParams.assetClass`
+ * to the right Pyth-backed Gateway endpoint:
+ *
+ *   crypto     → /api/v1/crypto/price/{ticker}         free
+ *   fx         → /api/v1/fx/price/{ticker}             free
+ *   commodity  → /api/v1/commodity/price/{ticker}      free
+ *   stock      → /v1/stocks/{market}/price/{ticker} paid ($0.001 x402) — PR 2
+ *
+ * PR 1 scope: crypto / fx / commodity only. The stock branch returns a
+ * `ProviderError { code: 'insufficient-funds' }` until the x402 signing
+ * wrapper lands, so callers get a useful message instead of a wire-level
+ * 402.
+ *
+ * Response shape from Gateway: Pyth delivers `{ price, confidence, timestamp }`
+ * — no 24h change, no market cap, no volume. Legacy CoinGecko-shaped fields
+ * (`change24hPct`, `volume24hUsd`, `marketCapUsd`) come back as `NaN` for
+ * non-crypto classes; views treat NaN as "not applicable" and render a dash.
+ */
+import { blockrunGet, blockrunGetPaid, cached, normalizePythSymbol, TTL } from './client.js';
+function endpointFor(assetClass, ticker, market) {
+    switch (assetClass) {
+        case 'crypto':
+            return { path: `/api/v1/crypto/price/${ticker}`, endpoint: '/api/v1/crypto/price', paid: false };
+        case 'fx':
+            return { path: `/api/v1/fx/price/${ticker}`, endpoint: '/api/v1/fx/price', paid: false };
+        case 'commodity':
+            return { path: `/api/v1/commodity/price/${ticker}`, endpoint: '/api/v1/commodity/price', paid: false };
+        case 'stock':
+            if (!market) {
+                return {
+                    kind: 'not-found',
+                    code: 'missing-market-code',
+                    message: `Stock queries require a market code (us/hk/jp/kr/gb/de/fr/nl/ie/lu/cn/ca). Got ticker "${ticker}" with none.`,
+                };
+            }
+            return {
+                path: `/api/v1/stocks/${market}/price/${ticker}`,
+                endpoint: `/api/v1/stocks/${market}/price`,
+                paid: true,
+            };
+        default: {
+            const _exhaust = assetClass;
+            void _exhaust;
+            return { kind: 'unknown', code: 'unsupported-asset-class', message: `Unsupported asset class` };
+        }
+    }
+}
+export const blockrunPriceFetcher = {
+    providerName: 'blockrun',
+    transformQuery(input) {
+        const assetClass = (input.assetClass ?? 'crypto');
+        const rawTicker = String(input.ticker ?? '').trim();
+        if (!rawTicker)
+            throw new Error('PriceQueryParams.ticker is required');
+        // Stocks: keep ticker as-is (`AAPL`, `7203`, `HSBA`). Everything else:
+        // Pyth-style `BASE-QUOTE`, upper-cased, `-USD` suffix defaulted.
+        const ticker = assetClass === 'stock'
+            ? rawTicker.toUpperCase()
+            : normalizePythSymbol(rawTicker);
+        return { ticker, assetClass, market: input.market };
+    },
+    async fetchData(query) {
+        const assetClass = (query.assetClass ?? 'crypto');
+        const resolved = endpointFor(assetClass, query.ticker, query.market);
+        if ('kind' in resolved)
+            return resolved;
+        const cacheKey = `blockrun:${assetClass}:${query.market ?? ''}:${query.ticker}`;
+        return cached(cacheKey, TTL.price, async () => {
+            if (resolved.paid) {
+                return blockrunGetPaid(resolved.path, {
+                    endpoint: resolved.endpoint,
+                    costUsd: 0.001,
+                });
+            }
+            return blockrunGet(resolved.path, {
+                endpoint: resolved.endpoint,
+                paid: false,
+                costUsd: 0,
+            });
+        });
+    },
+    transformData(raw, query) {
+        if (!raw || typeof raw !== 'object') {
+            return { kind: 'upstream-error', code: 'schema-mismatch', message: 'Gateway returned non-object payload' };
+        }
+        const payload = raw;
+        if (typeof payload.price !== 'number' || !Number.isFinite(payload.price)) {
+            return {
+                kind: 'upstream-error',
+                code: 'schema-mismatch',
+                message: `Gateway payload missing numeric 'price' for ${query.ticker}`,
+            };
+        }
+        // Pyth feeds don't carry 24h deltas; future Gateway upgrades might add
+        // them as optional fields, so we read defensively via indexed access.
+        const change = payload['change_24h_pct'];
+        const volume = payload['volume_24h_usd'];
+        const marketCap = payload['market_cap_usd'];
+        return {
+            ticker: query.ticker,
+            priceUsd: payload.price,
+            change24hPct: typeof change === 'number' ? change : NaN,
+            volume24hUsd: typeof volume === 'number' ? volume : NaN,
+            marketCapUsd: typeof marketCap === 'number' ? marketCap : NaN,
+        };
+    },
+};

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

@@ -0,0 +1,20 @@
+/**
+ * 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 type { ProviderError } from '../standard-models.js';
+export declare const TICKER_TO_ID: Record<string, string>;
+export declare function resolveProviderId(ticker: string): string;
+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;
+export declare function coingeckoGet(path: string): Promise<unknown | ProviderError>;
+export declare const TTL: {
+    readonly price: number;
+    readonly ohlcv: number;
+    readonly trending: number;
+    readonly markets: number;
+};