@blockrun/franklin 3.15.13 → 3.15.14

package/dist/agent/context.js

@@ -315,6 +315,7 @@ function getToolPatternsSection() {
 Your training data is frozen in the past. Live-world questions MUST be answered from tool results, not memory.
 - Any question about a current price, quote, market state, or "should I buy/sell/hold X" → use **TradingMarket** (crypto/FX/commodity are free; stocks cost \$0.001 via the wallet).
 - Any "what happened / why did it change / latest news on X" → use **ExaAnswer** for a cited synthesized answer, or **ExaSearch** + **ExaReadUrls** when you need more depth.
+- Any "what are the odds of X / will Y happen / Polymarket on Z / Kalshi market for W" → use **PredictionMarket** (\$0.001 search; \$0.005 cross-platform / smart money).
 - If the user names a thing you don't recognize (a company, ticker, project), don't demand clarification — call the research tools and figure it out. You have a wallet to spend on exactly this.
 - If a tool returns an error (rate-limit, 404, insufficient funds), say so plainly and suggest the next action. Don't silently fall back to memory.
 
@@ -326,6 +327,13 @@ Your training data is frozen in the past. Live-world questions MUST be answered
 
 If you find yourself about to emit one of these, stop and call the tool instead. If you don't know which ticker the user means, call ExaSearch or AskUser — never deflect.
 
+**Prediction markets (PredictionMarket).** When the user asks about real-world odds — elections, "will X happen by year-end", "Polymarket on Y", "Kalshi market for Z", "what are the odds of recession" — use **PredictionMarket** instead of guessing. Four actions:
+- \`searchPolymarket\` (\$0.001) and \`searchKalshi\` (\$0.001) — search markets by keyword. Run them **in parallel** when the user wants the current odds; comparing implied probability across two venues is the high-value answer.
+- \`crossPlatform\` (\$0.005) — pre-matched pairs of equivalent markets across Polymarket and Kalshi. Use when the user wants arbitrage candidates or wants to know "where does the consensus disagree".
+- \`smartMoney\` (\$0.005) — top-wallet flow on a specific Polymarket \`condition_id\`. Get the \`condition_id\` from a prior \`searchPolymarket\` call.
+
+NEVER answer "what are the odds of X" from training-data memory — these are live markets that move every minute. NEVER claim "Polymarket doesn't have a market on this" without running \`searchPolymarket\` first. If both Polymarket and Kalshi return zero markets, say so explicitly with the searches you tried, then offer to broaden the query.
+
 **Trading verdicts (TradingSignal).** When the user asks "how does $TICKER look" / "should I buy X" / "is BTC overbought":
 - Run **TradingSignal** with default lookback (90d). Lower values leave MACD undefined.
 - The tool returns a **Verdict** section with \`Direction\`, \`Bull signals\`, \`Bear signals\`. Echo it directly. Do not soften "bullish" to "leaning slightly positive" — say what the data says.

package/dist/tools/index.js

@@ -29,6 +29,7 @@ import { jupiterQuoteCapability, jupiterSwapCapability } from './jupiter.js';
 import { base0xQuoteCapability, base0xSwapCapability } from './zerox-base.js';
 import { base0xGaslessSwapCapability } from './zerox-gasless.js';
 import { defiLlamaProtocolsCapability, defiLlamaProtocolCapability, defiLlamaChainsCapability, defiLlamaYieldsCapability, defiLlamaPriceCapability, } from './defillama.js';
+import { predictionMarketCapability } from './prediction.js';
 import { modalCapabilities } from './modal.js';
 import { createTradingCapabilities } from './trading-execute.js';
 import { Portfolio } from '../trading/portfolio.js';
@@ -159,6 +160,7 @@ export const allCapabilities = [
     defiLlamaChainsCapability,
     defiLlamaYieldsCapability,
     defiLlamaPriceCapability,
+    predictionMarketCapability, // Polymarket / Kalshi / matching / smart money via Predexon
     // Modal GPU sandbox tools — registered but hidden by default (not in
     // CORE_TOOL_NAMES). Agent must `ActivateTool({names:["ModalCreate",...]})`
     // before they appear in its tool inventory. High-cost ($0.40/H100 create)

package/dist/tools/prediction.d.ts

@@ -0,0 +1,24 @@
+/**
+ * PredictionMarket — unified access to Polymarket / Kalshi / cross-platform
+ * matching / smart-money endpoints via the BlockRun gateway. Each call
+ * settles via x402 against the user's USDC wallet.
+ *
+ * Powered server-side by Predexon; surfaced to the agent as a single
+ * action-dispatched tool so the inventory stays small. Keep one cohesive
+ * tool — the way TradingMarket bundles 6 actions — instead of forty
+ * one-shot capabilities, otherwise weak models start hallucinating tool
+ * names.
+ *
+ *   searchPolymarket   $0.001  query Polymarket markets (event filter, sort)
+ *   searchKalshi       $0.001  query Kalshi markets
+ *   crossPlatform      $0.005  matching market pairs across Polymarket+Kalshi
+ *                              (the arbitrage / consensus signal)
+ *   smartMoney         $0.005  smart-money positioning on one Polymarket
+ *                              condition_id (top wallet flow + side bias)
+ *
+ * Output is filtered + truncated on the way back so a single call never
+ * dumps 100 markets into the agent's context. Default 20 rows; agents that
+ * need more should narrow the search.
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+export declare const predictionMarketCapability: CapabilityHandler;

package/dist/tools/prediction.js

@@ -0,0 +1,340 @@
+/**
+ * PredictionMarket — unified access to Polymarket / Kalshi / cross-platform
+ * matching / smart-money endpoints via the BlockRun gateway. Each call
+ * settles via x402 against the user's USDC wallet.
+ *
+ * Powered server-side by Predexon; surfaced to the agent as a single
+ * action-dispatched tool so the inventory stays small. Keep one cohesive
+ * tool — the way TradingMarket bundles 6 actions — instead of forty
+ * one-shot capabilities, otherwise weak models start hallucinating tool
+ * names.
+ *
+ *   searchPolymarket   $0.001  query Polymarket markets (event filter, sort)
+ *   searchKalshi       $0.001  query Kalshi markets
+ *   crossPlatform      $0.005  matching market pairs across Polymarket+Kalshi
+ *                              (the arbitrage / consensus signal)
+ *   smartMoney         $0.005  smart-money positioning on one Polymarket
+ *                              condition_id (top wallet flow + side bias)
+ *
+ * Output is filtered + truncated on the way back so a single call never
+ * dumps 100 markets into the agent's context. Default 20 rows; agents that
+ * need more should narrow the search.
+ */
+import { getOrCreateWallet, getOrCreateSolanaWallet, createPaymentPayload, createSolanaPaymentPayload, parsePaymentRequired, extractPaymentDetails, solanaKeyToBytes, SOLANA_NETWORK, } from '@blockrun/llm';
+import { loadChain, API_URLS, VERSION } from '../config.js';
+import { logger } from '../logger.js';
+const TIMEOUT_MS = 30_000;
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 50;
+// ─── Shared GET-with-x402 flow ────────────────────────────────────────────
+async function getWithPayment(path, query, ctx) {
+    const chain = loadChain();
+    const apiUrl = API_URLS[chain];
+    const qs = new URLSearchParams();
+    for (const [k, v] of Object.entries(query)) {
+        if (v == null || v === '')
+            continue;
+        qs.set(k, String(v));
+    }
+    const queryStr = qs.toString();
+    const endpoint = `${apiUrl}${path}${queryStr ? `?${queryStr}` : ''}`;
+    const headers = {
+        Accept: 'application/json',
+        'User-Agent': `franklin/${VERSION}`,
+    };
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    const onAbort = () => controller.abort();
+    ctx.abortSignal.addEventListener('abort', onAbort, { once: true });
+    try {
+        let response = await fetch(endpoint, { method: 'GET', signal: controller.signal, headers });
+        if (response.status === 402) {
+            const paymentHeaders = await signPayment(response, chain, endpoint);
+            if (!paymentHeaders) {
+                throw new Error('Payment signing failed — check wallet balance');
+            }
+            response = await fetch(endpoint, {
+                method: 'GET',
+                signal: controller.signal,
+                headers: { ...headers, ...paymentHeaders },
+            });
+        }
+        if (!response.ok) {
+            const errText = await response.text().catch(() => '');
+            throw new Error(`PredictionMarket ${path} failed (${response.status}): ${errText.slice(0, 200)}`);
+        }
+        return (await response.json());
+    }
+    finally {
+        clearTimeout(timeout);
+        ctx.abortSignal.removeEventListener('abort', onAbort);
+    }
+}
+async function signPayment(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 PredictionMarket call',
+                maxTimeoutSeconds: details.maxTimeoutSeconds || 60,
+                extra: details.extra,
+            });
+            return { 'PAYMENT-SIGNATURE': payload };
+        }
+        const wallet = await 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 PredictionMarket call',
+            maxTimeoutSeconds: details.maxTimeoutSeconds || 60,
+            extra: details.extra,
+        });
+        return { 'PAYMENT-SIGNATURE': payload };
+    }
+    catch (err) {
+        logger.warn(`[franklin] PredictionMarket payment error: ${err.message}`);
+        return null;
+    }
+}
+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;
+}
+// ─── Formatting helpers ────────────────────────────────────────────────────
+function formatUsd(value) {
+    if (value == null || !Number.isFinite(value))
+        return 'n/a';
+    if (value >= 1e9)
+        return `$${(value / 1e9).toFixed(2)}B`;
+    if (value >= 1e6)
+        return `$${(value / 1e6).toFixed(2)}M`;
+    if (value >= 1e3)
+        return `$${(value / 1e3).toFixed(1)}K`;
+    return `$${value.toFixed(2)}`;
+}
+function formatPct(value, digits = 1) {
+    if (value == null || !Number.isFinite(value))
+        return 'n/a';
+    return `${(value * 100).toFixed(digits)}%`;
+}
+// API responses sometimes come wrapped as `{data: [...], pagination: ...}`,
+// other times as a bare array. Normalise to an array.
+function unwrapList(raw) {
+    if (Array.isArray(raw))
+        return raw;
+    if (raw && typeof raw === 'object') {
+        const obj = raw;
+        if (Array.isArray(obj.data))
+            return obj.data;
+        if (Array.isArray(obj.markets))
+            return obj.markets;
+        if (Array.isArray(obj.pairs))
+            return obj.pairs;
+        if (Array.isArray(obj.results))
+            return obj.results;
+    }
+    return [];
+}
+async function execute(input, ctx) {
+    const { action, search, status, sort, limit, conditionId } = input;
+    const cappedLimit = Math.min(Math.max(1, limit ?? DEFAULT_LIMIT), MAX_LIMIT);
+    if (!action) {
+        return { output: 'Error: action is required (searchPolymarket | searchKalshi | crossPlatform | smartMoney)', isError: true };
+    }
+    try {
+        switch (action) {
+            case 'searchPolymarket': {
+                const raw = await getWithPayment('/api/v1/pm/polymarket/markets', {
+                    search,
+                    status: status ?? 'active',
+                    sort: sort ?? 'volume',
+                    limit: cappedLimit,
+                }, ctx);
+                const markets = unwrapList(raw);
+                if (markets.length === 0) {
+                    return { output: 'No Polymarket markets matched the filters.' };
+                }
+                const lines = [
+                    `## Polymarket — ${markets.length} market${markets.length === 1 ? '' : 's'}` +
+                        (search ? ` · search="${search}"` : '') +
+                        (status ? ` · status=${status}` : '') +
+                        ` · sort=${sort ?? 'volume'}`,
+                    '',
+                ];
+                markets.forEach((m, i) => {
+                    const yesPx = m.outcomes && m.outcome_prices && m.outcomes.length === m.outcome_prices.length
+                        ? m.outcomes.map((o, j) => `${o}=${formatPct(m.outcome_prices[j])}`).join(' / ')
+                        : 'n/a';
+                    const cid = m.condition_id ? ` · condition_id=\`${m.condition_id.slice(0, 14)}…\`` : '';
+                    lines.push(`${i + 1}. **${m.question || m.market_slug || 'untitled'}**${cid}\n` +
+                        `   prices: ${yesPx} · vol: ${formatUsd(m.volume)} · liq: ${formatUsd(m.liquidity)}` +
+                        (m.end_date ? ` · ends ${m.end_date.slice(0, 10)}` : ''));
+                });
+                lines.push('', `_$0.001 paid via x402._`);
+                return { output: lines.join('\n') };
+            }
+            case 'searchKalshi': {
+                const raw = await getWithPayment('/api/v1/pm/kalshi/markets', {
+                    search,
+                    status: status ?? 'open',
+                    sort: sort ?? 'volume',
+                    limit: cappedLimit,
+                }, ctx);
+                const markets = unwrapList(raw);
+                if (markets.length === 0) {
+                    return { output: 'No Kalshi markets matched the filters.' };
+                }
+                const lines = [
+                    `## Kalshi — ${markets.length} market${markets.length === 1 ? '' : 's'}` +
+                        (search ? ` · search="${search}"` : '') +
+                        ` · status=${status ?? 'open'} · sort=${sort ?? 'volume'}`,
+                    '',
+                ];
+                markets.forEach((m, i) => {
+                    // Kalshi quotes prices in cents (0–100). Surface them as a tight
+                    // bid/ask so the agent can read implied probability at a glance.
+                    const bid = m.yes_bid != null ? `${m.yes_bid}¢` : 'n/a';
+                    const ask = m.yes_ask != null ? `${m.yes_ask}¢` : 'n/a';
+                    const ticker = m.ticker ? ` · ticker=\`${m.ticker}\`` : '';
+                    lines.push(`${i + 1}. **${m.title || m.ticker || 'untitled'}**${ticker}\n` +
+                        `   yes ${bid}/${ask} · vol: ${m.volume?.toLocaleString() ?? 'n/a'} · OI: ${m.open_interest?.toLocaleString() ?? 'n/a'}` +
+                        (m.close_time ? ` · closes ${m.close_time.slice(0, 10)}` : ''));
+                });
+                lines.push('', `_$0.001 paid via x402._`);
+                return { output: lines.join('\n') };
+            }
+            case 'crossPlatform': {
+                const raw = await getWithPayment('/api/v1/pm/matching-markets/pairs', {
+                    limit: cappedLimit,
+                }, ctx);
+                const pairs = unwrapList(raw);
+                if (pairs.length === 0) {
+                    return { output: 'No matched market pairs available right now.' };
+                }
+                const lines = [
+                    `## Cross-platform matched pairs — ${pairs.length}`,
+                    '_Polymarket ↔ Kalshi equivalent markets. Use these to compare implied probabilities across venues._',
+                    '',
+                ];
+                pairs.forEach((p, i) => {
+                    const sim = p.similarity != null ? ` · similarity ${formatPct(p.similarity, 0)}` : '';
+                    lines.push(`${i + 1}. **Polymarket:** ${p.polymarket_question || '(untitled)'}\n` +
+                        `   **Kalshi:** ${p.kalshi_title || '(untitled)'}` +
+                        (p.kalshi_ticker ? ` · ticker=\`${p.kalshi_ticker}\`` : '') +
+                        sim);
+                });
+                lines.push('', `_$0.005 paid via x402._`);
+                return { output: lines.join('\n') };
+            }
+            case 'smartMoney': {
+                if (!conditionId) {
+                    return { output: 'Error: conditionId is required for smartMoney (Polymarket condition_id from a prior searchPolymarket call)', isError: true };
+                }
+                const path = `/api/v1/pm/polymarket/market/${encodeURIComponent(conditionId)}/smart-money`;
+                const data = await getWithPayment(path, {}, ctx);
+                const buyers = (data.buyers ?? []).slice(0, 5);
+                const sellers = (data.sellers ?? []).slice(0, 5);
+                const lines = [
+                    `## Smart money — \`${conditionId.slice(0, 14)}…\``,
+                ];
+                if (data.net_yes_size != null || data.net_no_size != null) {
+                    const yesSize = formatUsd(data.net_yes_size);
+                    const noSize = formatUsd(data.net_no_size);
+                    lines.push(`**Net flow:** YES ${yesSize} / NO ${noSize}`);
+                }
+                if (buyers.length > 0) {
+                    lines.push('', '**Top buyers**');
+                    buyers.forEach((b, i) => {
+                        const w = b.wallet ? `${b.wallet.slice(0, 8)}…${b.wallet.slice(-4)}` : 'unknown';
+                        lines.push(`${i + 1}. ${w} — ${formatUsd(b.size)} on ${b.outcome ?? 'unknown side'}`);
+                    });
+                }
+                if (sellers.length > 0) {
+                    lines.push('', '**Top sellers**');
+                    sellers.forEach((s, i) => {
+                        const w = s.wallet ? `${s.wallet.slice(0, 8)}…${s.wallet.slice(-4)}` : 'unknown';
+                        lines.push(`${i + 1}. ${w} — ${formatUsd(s.size)} on ${s.outcome ?? 'unknown side'}`);
+                    });
+                }
+                if (buyers.length === 0 && sellers.length === 0) {
+                    lines.push('No smart-money flow recorded for this market yet.');
+                }
+                lines.push('', `_$0.005 paid via x402._`);
+                return { output: lines.join('\n') };
+            }
+            default:
+                return {
+                    output: `Error: unknown action "${action}". Use: searchPolymarket, searchKalshi, crossPlatform, smartMoney`,
+                    isError: true,
+                };
+        }
+    }
+    catch (err) {
+        return { output: `Error: ${err.message}`, isError: true };
+    }
+}
+export const predictionMarketCapability = {
+    spec: {
+        name: 'PredictionMarket',
+        description: 'Real prediction market data via the BlockRun gateway (powered by Predexon). Use for any "what are the odds of X" / "Polymarket on Y" / "Kalshi market for Z" question. ' +
+            'Actions: ' +
+            '`searchPolymarket` (search Polymarket markets — $0.001), ' +
+            '`searchKalshi` (search Kalshi markets — $0.001), ' +
+            '`crossPlatform` (matched pairs across Polymarket+Kalshi for arbitrage / consensus — $0.005), ' +
+            '`smartMoney` (smart-money positioning on a Polymarket condition_id — $0.005). ' +
+            'Polymarket and Kalshi are the two largest legit prediction markets; cross-platform matching is unique to BlockRun. ' +
+            'For "should I bet on X" / "what does the market price imply": run searchPolymarket AND searchKalshi in parallel and compare implied probabilities — divergence is the signal.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['searchPolymarket', 'searchKalshi', 'crossPlatform', 'smartMoney'],
+                    description: 'Which prediction-market query to run. See tool description for cost per action.',
+                },
+                search: {
+                    type: 'string',
+                    description: 'Search query (3-100 chars). Used by searchPolymarket / searchKalshi. Skip for crossPlatform/smartMoney.',
+                },
+                status: {
+                    type: 'string',
+                    description: 'Polymarket: active | closed | archived (default active). Kalshi: open | closed (default open).',
+                },
+                sort: {
+                    type: 'string',
+                    description: 'Polymarket: volume | liquidity | created (default volume). Kalshi: volume | open_interest | price_desc | price_asc | close_time (default volume).',
+                },
+                limit: {
+                    type: 'number',
+                    description: `Max results (default ${DEFAULT_LIMIT}, hard cap ${MAX_LIMIT}).`,
+                },
+                conditionId: {
+                    type: 'string',
+                    description: 'Polymarket condition_id. Required for smartMoney. Get one from a prior searchPolymarket call.',
+                },
+            },
+            required: ['action'],
+        },
+    },
+    execute,
+    concurrent: true,
+};

package/dist/tools/tool-categories.js

@@ -44,6 +44,11 @@ export const CORE_TOOL_NAMES = new Set([
     // training-data guessing.
     'TradingMarket',
     'TradingSignal',
+    // Prediction market data — Polymarket, Kalshi, cross-platform matching,
+    // smart money. The "what are the odds of X" / "Polymarket on Y"
+    // category. Cross-platform pair lookup is unique to the gateway and
+    // is the kind of data a non-wallet agent fundamentally cannot reach.
+    'PredictionMarket',
     // Research — synthesized answers with real citations, semantic web
     // search, and clean URL fetching. Any factual current-events question
     // ("why did X drop?") should route here rather than the model's prior.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/franklin",
-  "version": "3.15.13",
+  "version": "3.15.14",
   "description": "Franklin — The AI agent with a wallet. Spends USDC autonomously to get real work done. Pay per action, no subscriptions.",
   "type": "module",
   "exports": {