pmxt-core 2.50.16 → 2.51.1

package/dist/exchanges/hunch/index.js

@@ -0,0 +1,330 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HunchExchange = void 0;
+const BaseExchange_1 = require("../../BaseExchange");
+const errors_1 = require("../../errors");
+const validation_1 = require("../../utils/validation");
+const openapi_1 = require("../../utils/openapi");
+const auth_1 = require("./auth");
+const fetcher_1 = require("./fetcher");
+const normalizer_1 = require("./normalizer");
+const websocket_1 = require("./websocket");
+const errors_2 = require("./errors");
+const api_1 = require("./api");
+const utils_1 = require("./utils");
+const AGENT_PREFIX = '/api/agent/v1';
+const SIMPLE_TIER_MAX_USD = 10;
+// ---------------------------------------------------------------------------
+// x402 / EIP-3009 codec — ported VERBATIM from the Hunch SDK
+// (packages/hunch-agent-sdk/src/x402.ts) so the signature + X-PAYMENT encoding
+// the route decodes are byte-correct. pmxt-core cannot import the Hunch SDK,
+// so the minimal recipe is inlined here.
+// ---------------------------------------------------------------------------
+const TRANSFER_WITH_AUTHORIZATION_TYPES = {
+    TransferWithAuthorization: [
+        { name: 'from', type: 'address' },
+        { name: 'to', type: 'address' },
+        { name: 'value', type: 'uint256' },
+        { name: 'validAfter', type: 'uint256' },
+        { name: 'validBefore', type: 'uint256' },
+        { name: 'nonce', type: 'bytes32' },
+    ],
+};
+const DEFAULT_AUTH_VALID_SECONDS = 10 * 60;
+const CLOCK_SKEW_SECONDS = 60;
+/** Validate + extract the single Base-USDC "exact" requirement from a 402 body. */
+function parseX402Challenge(body) {
+    const challenge = body;
+    const accepts = challenge?.accepts;
+    const first = Array.isArray(accepts) ? accepts[0] : undefined;
+    if (!first || typeof first !== 'object') {
+        throw new errors_1.InvalidOrder('Hunch 402 challenge did not advertise a payment requirement.', 'Hunch');
+    }
+    if (first.scheme !== 'exact') {
+        throw new errors_1.InvalidOrder(`Unsupported Hunch x402 scheme: ${String(first.scheme)}`, 'Hunch');
+    }
+    if (first.network !== 'base') {
+        throw new errors_1.InvalidOrder(`Unsupported Hunch x402 network: ${String(first.network)}`, 'Hunch');
+    }
+    if (!first.payTo || !first.asset || !first.extra) {
+        throw new errors_1.InvalidOrder('Hunch 402 challenge is missing payTo / asset / domain extra.', 'Hunch');
+    }
+    return first;
+}
+function randomNonce() {
+    const bytes = new Uint8Array(32);
+    globalThis.crypto.getRandomValues(bytes);
+    let out = '0x';
+    for (const b of bytes)
+        out += b.toString(16).padStart(2, '0');
+    return out;
+}
+function buildTransferAuthorizationTypedData(params) {
+    const now = params.now ?? Math.floor(Date.now() / 1000);
+    const validAfter = Math.max(0, Math.floor(now) - CLOCK_SKEW_SECONDS);
+    const validBefore = Math.floor(now) + DEFAULT_AUTH_VALID_SECONDS;
+    const nonce = randomNonce();
+    const to = params.requirements.payTo;
+    const value = params.requirements.maxAmountRequired;
+    const authorization = { from: params.from, to, value, validAfter, validBefore, nonce };
+    const typedData = {
+        domain: {
+            name: params.requirements.extra.name,
+            version: params.requirements.extra.version,
+            chainId: utils_1.BASE_CHAIN_ID,
+            verifyingContract: params.requirements.asset,
+        },
+        types: TRANSFER_WITH_AUTHORIZATION_TYPES,
+        primaryType: 'TransferWithAuthorization',
+        message: {
+            from: params.from,
+            to,
+            value: BigInt(value),
+            validAfter: BigInt(validAfter),
+            validBefore: BigInt(validBefore),
+            nonce,
+        },
+    };
+    return { typedData, authorization };
+}
+/** Encode a signed authorization into the base64 `X-PAYMENT` header value. */
+function encodeXPaymentHeader(signed) {
+    const payload = {
+        x402Version: 1,
+        scheme: 'exact',
+        network: 'base',
+        payload: {
+            signature: signed.signature,
+            authorization: {
+                from: signed.from,
+                to: signed.to,
+                value: signed.value,
+                validAfter: signed.validAfter,
+                validBefore: signed.validBefore,
+                nonce: signed.nonce,
+            },
+        },
+    };
+    return Buffer.from(JSON.stringify(payload), 'utf8').toString('base64');
+}
+// ---------------------------------------------------------------------------
+// HunchExchange
+// ---------------------------------------------------------------------------
+class HunchExchange extends BaseExchange_1.PredictionMarketExchange {
+    capabilityOverrides = {
+        fetchOrderBook: 'emulated',
+        createOrder: true,
+        cancelOrder: false,
+        fetchOrder: false,
+        fetchOpenOrders: false,
+        fetchBalance: true,
+        fetchPositions: true,
+        fetchSeries: false,
+        watchOrderBook: 'emulated',
+        watchTrades: 'emulated',
+    };
+    auth;
+    fetcher;
+    normalizer;
+    hunchBaseUrl;
+    ws;
+    constructor(credentials) {
+        super(credentials);
+        this.rateLimit = 500;
+        this.auth = new auth_1.HunchAuth(credentials ?? {});
+        this.hunchBaseUrl = credentials?.baseUrl || utils_1.DEFAULT_BASE_URL;
+        const descriptor = (0, openapi_1.parseOpenApiSpec)(api_1.hunchApiSpec, this.hunchBaseUrl);
+        this.defineImplicitApi(descriptor);
+        const ctx = {
+            http: this.http,
+            callApi: this.callApi.bind(this),
+            getHeaders: () => this.getHeaders(),
+        };
+        this.fetcher = new fetcher_1.HunchFetcher(ctx, this.hunchBaseUrl);
+        this.normalizer = new normalizer_1.HunchNormalizer();
+    }
+    get name() {
+        return 'Hunch';
+    }
+    getHeaders() {
+        return this.auth.getHeaders();
+    }
+    sign(_method, _path, _params) {
+        return this.getHeaders();
+    }
+    mapImplicitApiError(error) {
+        throw errors_2.hunchErrorMapper.mapError(error);
+    }
+    // -- Market data ----------------------------------------------------------
+    async fetchMarketsImpl(params) {
+        const raw = await this.fetcher.fetchRawMarkets(params);
+        return raw.map((m) => this.normalizer.normalizeMarket(m)).filter((m) => m !== null);
+    }
+    async fetchEventsImpl(params) {
+        // Hunch has no series concept; honor `series` by returning [].
+        if (params.series !== undefined)
+            return [];
+        const raw = await this.fetcher.fetchRawEvents(params);
+        return raw.map((m) => this.normalizer.normalizeEvent(m)).filter((e) => e !== null);
+    }
+    async fetchOHLCV(outcomeId, params) {
+        if (!params.resolution) {
+            throw new Error('fetchOHLCV requires a resolution parameter.');
+        }
+        const { side } = (0, utils_1.parseHunchSide)(outcomeId);
+        const research = await this.fetcher.fetchRawOHLCV(outcomeId, params);
+        return this.normalizer.normalizeOHLCV(research, params, side);
+    }
+    async fetchOrderBook(outcomeId, _limit, _params) {
+        const research = await this.fetcher.fetchRawOrderBook(outcomeId);
+        return this.normalizer.normalizeOrderBook(research, outcomeId);
+    }
+    async fetchTrades(outcomeId, params) {
+        (0, validation_1.validateTradesLimit)(params.limit);
+        const rawTrades = await this.fetcher.fetchRawTrades(outcomeId, params);
+        return rawTrades.map((raw, i) => this.normalizer.normalizeTrade(raw, i));
+    }
+    // -- Trading (x402 money path) --------------------------------------------
+    async createOrder(params) {
+        if (params.type === 'limit') {
+            throw new errors_1.InvalidOrder('Hunch is parimutuel: limit orders are unsupported, market orders only.', 'Hunch');
+        }
+        if (params.side !== 'buy') {
+            throw new errors_1.InvalidOrder('Hunch markets are entry-only (parimutuel pool): only side "buy" is supported.', 'Hunch');
+        }
+        const { marketId, side } = (0, utils_1.parseHunchSide)(params.outcomeId);
+        if (!marketId || !side) {
+            throw new errors_1.ValidationError(`Invalid Hunch outcomeId "${params.outcomeId}". Expected "{marketId}:{side}".`, 'outcomeId', 'Hunch');
+        }
+        const walletAddress = this.auth.requireWalletAddress('createOrder');
+        const account = this.auth.getAccount(); // throws if no privateKey to sign
+        const sizeUsd = params.amount;
+        const body = {
+            marketId,
+            side,
+            sizeUsd,
+            idemKey: this.buildIdemKey(marketId, side, walletAddress),
+            walletAddress,
+            simulate: false,
+        };
+        // Above the simple tier ($10) Hunch requires a price-locked quote.
+        if (sizeUsd > SIMPLE_TIER_MAX_USD) {
+            const quote = await this.fetcher.fetchRawQuote(marketId, side, sizeUsd, walletAddress);
+            body.quoteId = quote.quoteId;
+            body.minSharesOut = quote.suggestedMinSharesOut;
+        }
+        // x402 loop: serialize ONCE so the paid retry recomputes the same
+        // intentHash the 402 advertised (matches the Hunch SDK's `bet()`).
+        const serialized = JSON.stringify(body);
+        const tradeUrl = `${this.hunchBaseUrl}${AGENT_PREFIX}/trade`;
+        let res = await this.postTrade(tradeUrl, serialized);
+        if (res.status === 402) {
+            const requirements = parseX402Challenge(res.data);
+            const { typedData, authorization } = buildTransferAuthorizationTypedData({
+                from: walletAddress,
+                requirements,
+            });
+            const signature = (await account.signTypedData(typedData));
+            const paymentHeader = encodeXPaymentHeader({ ...authorization, signature });
+            res = await this.postTrade(tradeUrl, serialized, paymentHeader);
+        }
+        if (res.status < 200 || res.status >= 300) {
+            throw errors_2.hunchErrorMapper.mapError({
+                response: { status: res.status, data: res.data },
+                isAxiosError: true,
+            });
+        }
+        const receipt = res.data?.receipt ?? res.data;
+        return this.receiptToOrder(receipt, params);
+    }
+    async cancelOrder(_orderId) {
+        throw new errors_1.InvalidOrder('cancelOrder() is not supported by Hunch (parimutuel pool — bets cannot be cancelled).', 'Hunch');
+    }
+    async fetchOrder(_orderId) {
+        throw new errors_1.InvalidOrder('fetchOrder() is not supported by Hunch (parimutuel; use fetchPositions / getProof).', 'Hunch');
+    }
+    async fetchOpenOrders(_marketId) {
+        return []; // Parimutuel: no resting orders.
+    }
+    async fetchPositions() {
+        const walletAddress = this.auth.requireWalletAddress('fetchPositions');
+        const raw = await this.fetcher.fetchRawPositions(walletAddress);
+        return raw.map((p) => this.normalizer.normalizePosition(p));
+    }
+    async fetchBalance() {
+        const walletAddress = this.auth.requireWalletAddress('fetchBalance');
+        const raw = await this.fetcher.fetchRawBalance(walletAddress);
+        return this.normalizer.normalizeBalance(raw);
+    }
+    // -- Real-time (poll-based emulation) -------------------------------------
+    async watchOrderBook(outcomeId, _limit, _params = {}) {
+        if (!this.ws)
+            this.ws = this.makeWs();
+        return this.ws.watchOrderBook(outcomeId);
+    }
+    async watchTrades(outcomeId, _address, _since, _limit) {
+        if (!this.ws)
+            this.ws = this.makeWs();
+        return this.ws.watchTrades(outcomeId);
+    }
+    async close() {
+        if (this.ws) {
+            await this.ws.close();
+            this.ws = undefined;
+        }
+    }
+    // -- helpers --------------------------------------------------------------
+    makeWs() {
+        return new websocket_1.HunchWebSocket((id) => this.fetchOrderBook(id), (id, limit) => this.fetchTrades(id, { limit }));
+    }
+    /**
+     * POST the trade body via the axios client, NOT throwing on non-2xx so the
+     * 402 challenge can be read (validateStatus: always-true). Mirrors the SDK's
+     * fetch-based `post()` that inspects `res.status === 402`.
+     */
+    async postTrade(url, body, paymentHeader) {
+        return this.http.request({
+            url,
+            method: 'POST',
+            data: body,
+            headers: {
+                'Content-Type': 'application/json',
+                ...(paymentHeader ? { 'X-PAYMENT': paymentHeader } : {}),
+            },
+            transformRequest: [(d) => d], // body is already a JSON string
+            validateStatus: () => true,
+        });
+    }
+    /** Deterministic-but-unique idempotency key (≥8 chars per the schema). */
+    buildIdemKey(marketId, side, wallet) {
+        const bytes = new Uint8Array(8);
+        globalThis.crypto.getRandomValues(bytes);
+        let suffix = '';
+        for (const b of bytes)
+            suffix += b.toString(16).padStart(2, '0');
+        return `pmxt-${wallet.slice(2, 10)}-${marketId}-${side}-${suffix}`.slice(0, 128);
+    }
+    receiptToOrder(receipt, params) {
+        const shares = Number(receipt?.position?.shares ?? 0);
+        const priceCents = Number(receipt?.position?.avgPriceCents ?? 0);
+        const sizeUsd = Number(receipt?.sizeUsd ?? params.amount);
+        const ts = receipt?.recordedAt ? Date.parse(receipt.recordedAt) : Date.now();
+        return {
+            id: String(receipt?.tradeId ?? `hunch-${Date.now()}`),
+            marketId: params.marketId,
+            outcomeId: params.outcomeId,
+            side: 'buy',
+            type: 'market',
+            price: priceCents / 100,
+            amount: sizeUsd,
+            filled: sizeUsd,
+            filledShares: shares,
+            remaining: 0,
+            status: 'filled',
+            timestamp: Number.isFinite(ts) ? ts : Date.now(),
+            txHash: receipt?.txHash ?? null,
+            chain: 'base',
+        };
+    }
+}
+exports.HunchExchange = HunchExchange;

package/dist/exchanges/hunch/normalizer.d.ts

@@ -0,0 +1,56 @@
+import { OHLCVParams } from '../../BaseExchange';
+import { UnifiedMarket, UnifiedEvent, PriceCandle, OrderBook, Trade, Position, Balance } from '../../types';
+import { IExchangeNormalizer } from '../interfaces';
+import { HunchRawMarket, HunchRawResearch, HunchRawOddsHistoryPoint, HunchRawPosition, HunchRawReadiness, HunchRawQuote } from './fetcher';
+/**
+ * HunchNormalizer — pure venue→unified mappers. No I/O. Hunch is PARIMUTUEL:
+ * prices are implied odds (cents → 0..1), there is no real CLOB; the order book
+ * is emulated as a single level at the implied price with the pool as depth.
+ */
+export declare class HunchNormalizer implements IExchangeNormalizer<HunchRawMarket, HunchRawMarket> {
+    /**
+     * Normalize a market ref. `odds`/`ladder` (from a single-market quote or
+     * research read) price the outcomes live; the bare list path passes neither,
+     * so list outcomes carry price 0 (live odds ride on the detail reads —
+     * mirrors Myriad's "static on list, live on detail" model).
+     */
+    normalizeMarket(raw: HunchRawMarket, odds?: {
+        yesPriceCents: number | null;
+        noPriceCents: number | null;
+    }, ladder?: HunchRawResearch['ladder']): UnifiedMarket | null;
+    /**
+     * Hunch has no Event tier. When the event API is used, each market is wrapped
+     * as a single-market event so the cross-venue ingest pipeline still works.
+     */
+    normalizeEvent(raw: HunchRawMarket): UnifiedEvent | null;
+    /**
+     * Map a research payload's oddsHistory to candles. Each fill is a flat
+     * candle at its realized YES probability (Myriad's flat-candle approach).
+     * For an N-way outcome, points whose `outcomeKey` matches are used; binary
+     * markets ignore `outcomeId` and use the YES trajectory.
+     */
+    normalizeOHLCV(raw: HunchRawResearch, params: OHLCVParams, outcomeKey?: string): PriceCandle[];
+    /**
+     * Emulate a single-level order book at the market's implied price, with the
+     * pool size (or virtual liquidity) as depth. Reuses research → odds / ladder
+     * / stats. For an N-way market, the level reflects the requested rung's
+     * implied price; binary uses the YES (or NO) implied price.
+     */
+    normalizeOrderBook(raw: HunchRawResearch, outcomeId: string): OrderBook;
+    /** Map a research oddsHistory point to a public trade. */
+    normalizeTrade(raw: HunchRawOddsHistoryPoint, index: number): Trade;
+    /** Map an AgentPosition → unified Position (shares, entry/now cents → 0..1). */
+    normalizePosition(raw: HunchRawPosition): Position;
+    /** Map readiness → a single USDC balance entry. */
+    normalizeBalance(raw: HunchRawReadiness): Balance[];
+    /**
+     * Quote → a single emulated order-book level (alternative to research when a
+     * size-specific implied price is wanted). Not wired into fetchOrderBook by
+     * default; kept for callers that have a quote in hand.
+     */
+    normalizeQuoteOrderBook(quote: HunchRawQuote): OrderBook;
+    private sideOf;
+    /** Normalize a stored position `side` to a stable outcome-id token. */
+    private normalizeSideKey;
+    private parseTs;
+}

package/dist/exchanges/hunch/normalizer.js

@@ -0,0 +1,180 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HunchNormalizer = void 0;
+const metadata_1 = require("../../utils/metadata");
+const utils_1 = require("./utils");
+const price_1 = require("./price");
+const HUNCH_PROMOTED_EVENT_KEYS = ['id', 'slug', 'question', 'markets'];
+/**
+ * HunchNormalizer — pure venue→unified mappers. No I/O. Hunch is PARIMUTUEL:
+ * prices are implied odds (cents → 0..1), there is no real CLOB; the order book
+ * is emulated as a single level at the implied price with the pool as depth.
+ */
+class HunchNormalizer {
+    /**
+     * Normalize a market ref. `odds`/`ladder` (from a single-market quote or
+     * research read) price the outcomes live; the bare list path passes neither,
+     * so list outcomes carry price 0 (live odds ride on the detail reads —
+     * mirrors Myriad's "static on list, live on detail" model).
+     */
+    normalizeMarket(raw, odds, ladder) {
+        return (0, utils_1.mapHunchMarketToUnified)(raw, odds, ladder ?? null);
+    }
+    /**
+     * Hunch has no Event tier. When the event API is used, each market is wrapped
+     * as a single-market event so the cross-venue ingest pipeline still works.
+     */
+    normalizeEvent(raw) {
+        const um = this.normalizeMarket(raw);
+        if (!um)
+            return null;
+        return {
+            id: raw.id,
+            title: raw.question || raw.shortTitle || '',
+            description: raw.summary || '',
+            slug: raw.slug || raw.id,
+            markets: [um],
+            volume24h: 0,
+            volume: um.volume,
+            url: raw.links?.app || 'https://www.playhunch.xyz',
+            category: raw.category,
+            tags: raw.tokenSymbol ? [raw.tokenSymbol] : [],
+            sourceMetadata: (0, metadata_1.buildSourceMetadata)(raw, HUNCH_PROMOTED_EVENT_KEYS),
+        };
+    }
+    /**
+     * Map a research payload's oddsHistory to candles. Each fill is a flat
+     * candle at its realized YES probability (Myriad's flat-candle approach).
+     * For an N-way outcome, points whose `outcomeKey` matches are used; binary
+     * markets ignore `outcomeId` and use the YES trajectory.
+     */
+    normalizeOHLCV(raw, params, outcomeKey) {
+        const history = raw?.oddsHistory ?? [];
+        let points = history;
+        if (outcomeKey && outcomeKey !== 'yes' && outcomeKey !== 'no') {
+            const matched = history.filter((p) => p.outcomeKey === outcomeKey);
+            if (matched.length > 0)
+                points = matched;
+        }
+        const candles = points
+            .filter((p) => typeof p.yesPct === 'number')
+            .map((p) => {
+            const prob = p.yesPct / 100;
+            return {
+                timestamp: this.parseTs(p.at),
+                open: prob,
+                high: prob,
+                low: prob,
+                close: prob,
+                volume: p.sizeUsd,
+            };
+        });
+        if (params.limit && candles.length > params.limit) {
+            return candles.slice(-params.limit);
+        }
+        return candles;
+    }
+    /**
+     * Emulate a single-level order book at the market's implied price, with the
+     * pool size (or virtual liquidity) as depth. Reuses research → odds / ladder
+     * / stats. For an N-way market, the level reflects the requested rung's
+     * implied price; binary uses the YES (or NO) implied price.
+     */
+    normalizeOrderBook(raw, outcomeId) {
+        const side = this.sideOf(outcomeId);
+        let price = 0;
+        if (raw?.ladder && raw.ladder.outcomes.length > 0 && side !== 'yes' && side !== 'no') {
+            const rung = raw.ladder.outcomes.find((o) => o.key === side);
+            price = rung ? (0, price_1.resolveHunchPrice)(rung.impliedPct) : 0;
+        }
+        else {
+            const yesC = raw?.odds?.yesPriceCents ?? null;
+            const noC = raw?.odds?.noPriceCents ?? null;
+            price = side === 'no' ? (0, price_1.resolveHunchPrice)(noC) : (0, price_1.resolveHunchPrice)(yesC);
+        }
+        const pool = raw?.stats?.totalPoolUsd ?? 0;
+        const liquidity = Number(raw?.market?.virtualLiquidityUsd ?? 0);
+        const size = pool > 0 ? pool : liquidity > 0 ? liquidity : 1;
+        return {
+            bids: [{ price, size }],
+            asks: [{ price, size }],
+            timestamp: Date.now(),
+            lastTradePrice: price || undefined,
+        };
+    }
+    /** Map a research oddsHistory point to a public trade. */
+    normalizeTrade(raw, index) {
+        const prob = typeof raw.yesPct === 'number' ? raw.yesPct / 100 : 0;
+        return {
+            id: `${raw.at}-${index}`,
+            timestamp: this.parseTs(raw.at),
+            price: prob,
+            amount: Number(raw.sizeUsd || 0),
+            // Hunch oddsHistory is a one-sided fill tape (every entry is a buy
+            // into a side); direction isn't carried, so 'buy' from the taker view.
+            side: 'buy',
+        };
+    }
+    /** Map an AgentPosition → unified Position (shares, entry/now cents → 0..1). */
+    normalizePosition(raw) {
+        const side = this.normalizeSideKey(raw.side);
+        return {
+            marketId: raw.marketId,
+            outcomeId: `${raw.marketId}:${side}`,
+            outcomeLabel: raw.outcomeLabel || side,
+            size: Number(raw.shares || 0),
+            entryPrice: (0, price_1.resolveHunchPrice)(raw.avgEntryCents),
+            currentPrice: (0, price_1.resolveHunchPrice)(raw.currentCents),
+            unrealizedPnL: Number(raw.pnlUsd || 0),
+            txHash: null,
+            chain: 'base',
+        };
+    }
+    /** Map readiness → a single USDC balance entry. */
+    normalizeBalance(raw) {
+        const total = typeof raw?.usdcBalanceUsd === 'number' ? raw.usdcBalanceUsd : 0;
+        return [
+            {
+                currency: 'USDC',
+                total,
+                available: total,
+                locked: 0,
+            },
+        ];
+    }
+    /**
+     * Quote → a single emulated order-book level (alternative to research when a
+     * size-specific implied price is wanted). Not wired into fetchOrderBook by
+     * default; kept for callers that have a quote in hand.
+     */
+    normalizeQuoteOrderBook(quote) {
+        const price = (0, price_1.resolveHunchPrice)(quote.priceCents);
+        const pool = quote.stats?.totalPoolUsd ?? 0;
+        const size = pool > 0 ? pool : 1;
+        return {
+            bids: [{ price, size }],
+            asks: [{ price, size }],
+            timestamp: Date.now(),
+            lastTradePrice: price || undefined,
+        };
+    }
+    // -- helpers --------------------------------------------------------------
+    sideOf(outcomeId) {
+        const idx = outcomeId.lastIndexOf(':');
+        return idx >= 0 ? outcomeId.slice(idx + 1) : outcomeId;
+    }
+    /** Normalize a stored position `side` to a stable outcome-id token. */
+    normalizeSideKey(side) {
+        const s = (side || '').toLowerCase();
+        if (s === 'yes' || s === 'no' || s === 'up' || s === 'down')
+            return s;
+        return side; // bucket key (e.g. le-330m) — keep verbatim
+    }
+    parseTs(at) {
+        if (!at)
+            return Date.now();
+        const ms = Date.parse(at);
+        return Number.isFinite(ms) ? ms : Date.now();
+    }
+}
+exports.HunchNormalizer = HunchNormalizer;

package/dist/exchanges/hunch/price.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Resolve a probability (0..1) from a Hunch cents value (0..100).
+ * Hunch prices are integer cents on the parimutuel implied-odds scale.
+ */
+export declare function resolveHunchPrice(cents: number | null | undefined): number;

package/dist/exchanges/hunch/price.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveHunchPrice = resolveHunchPrice;
+/**
+ * Resolve a probability (0..1) from a Hunch cents value (0..100).
+ * Hunch prices are integer cents on the parimutuel implied-odds scale.
+ */
+function resolveHunchPrice(cents) {
+    if (typeof cents !== 'number' || !Number.isFinite(cents))
+        return 0;
+    return cents / 100;
+}

package/dist/exchanges/hunch/utils.d.ts

@@ -0,0 +1,79 @@
+import { UnifiedMarket } from '../../types';
+import { HunchRawMarket } from './fetcher';
+/**
+ * Canonical Hunch agent-platform base URL. Reads are keyless (CORS `*`);
+ * the trade route settles real Base USDC via x402 / EIP-3009.
+ */
+export declare const DEFAULT_BASE_URL = "https://www.playhunch.xyz";
+/** Base mainnet — the ONLY settlement chain on Hunch's agent rail. */
+export declare const BASE_CHAIN_ID = 8453;
+/** USDC on Base (the EIP-3009 `transferWithAuthorization` asset). */
+export declare const BASE_USDC_ADDRESS = "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913";
+/**
+ * Raw Hunch fields already promoted to first-class Unified columns — excluded
+ * from `sourceMetadata` so we capture only what the unified shape would drop
+ * (e.g. headline, deadlineLabel, feeRecipientLabel, defaultTicketUsd, links).
+ */
+export declare const HUNCH_PROMOTED_MARKET_KEYS: readonly ["id", "slug", "question", "summary", "category", "tokenSymbol", "chainId", "deadlineAt", "status", "feeBps", "virtualLiquidityUsd", "volumeUsd", "targetMarketCapUsd", "outcomes"];
+/**
+ * Map a Hunch status (open / closed / resolved) to the pmxt unified lifecycle
+ * vocabulary (active / inactive / closed). Unknown → 'active' (Hunch only lists
+ * `open` markets when `status=open`, so this is defensive).
+ */
+export declare function mapHunchStatus(status: string | undefined): 'active' | 'inactive' | 'closed';
+/**
+ * Translate the pmxt unified `status` filter into the Hunch `status` query
+ * value. Hunch only accepts `open` | `all`; 'inactive'/'closed' have no live
+ * listing, so they fold to `all` (the caller filters client-side afterwards).
+ */
+export declare function mapStatusToHunch(status?: string): 'open' | 'all' | undefined;
+/**
+ * Compose an outcome id that round-trips back to a Hunch trade `side`.
+ *
+ * Encoding: `${marketId}:${side}` where `side` is `yes` | `no` for binary
+ * markets, or the parimutuel bucket `key` (e.g. `le-330m`, `up`, `down`,
+ * a date-window key) for N-way markets. `parseHunchSide()` reverses it.
+ */
+export declare function buildOutcomeId(marketId: string, side: string): string;
+/**
+ * Reverse {@link buildOutcomeId}: pull the Hunch `side` token back out of a
+ * unified `outcomeId`. The market id itself may contain a `:` is NOT a concern —
+ * Hunch ids are slug-shaped (`[a-z0-9-]`), so the FIRST colon never appears
+ * inside an id; we split on the LAST colon to be safe regardless.
+ */
+export declare function parseHunchSide(outcomeId: string): {
+    marketId: string;
+    side: string;
+};
+/**
+ * Shared market normalizer used by both the live fetch path and the (rare)
+ * direct-mapping helper. Pulls a Hunch market ref into a {@link UnifiedMarket}.
+ *
+ * - Binary markets (`outcomes == null`) get YES/NO outcomes priced from `odds`
+ *   when supplied (research/quote-derived), else flat 0 (the list endpoint
+ *   does not carry live odds — they ride on the quote/research single-market
+ *   reads, matching Myriad's "static on list, live on detail" model).
+ * - N-way markets expand `outcomes[]` into one {@link MarketOutcome} per rung,
+ *   carrying `impliedPct/100` as the price when a live ladder is supplied.
+ *
+ * `outcomeId` round-trips to a Hunch `side` (see {@link buildOutcomeId}).
+ */
+export declare function mapHunchMarketToUnified(raw: HunchRawMarket, odds?: {
+    yesPriceCents: number | null;
+    noPriceCents: number | null;
+}, ladder?: {
+    outcomes: HunchLadderOutcome[];
+} | null): UnifiedMarket | null;
+/** Minimal live-ladder rung shape (mirrors AgentLadderOutcome) used for pricing. */
+export interface HunchLadderOutcome {
+    key: string;
+    label: string;
+    shortLabel: string;
+    lowerUsd: number | null;
+    upperUsd: number | null;
+    startAt?: string | null;
+    endAt?: string | null;
+    impliedPct: number;
+    backedUsd: number;
+    isCurrent: boolean;
+}