@blockrun/franklin 3.8.8 → 3.8.9

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

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