@liberfi.io/react-predict 0.1.1 → 0.1.3

package/dist/server.d.mts

@@ -1,2 +1,997 @@
-export { B as BalanceResponse, at as BuildClobAuthMessageInput, aE as BuildOrderMessageInput, aG as BuildSignedOrderInput, ak as CLOB_AUTH_DOMAIN, al as CLOB_AUTH_TYPES, au as CTF_EXCHANGE_ADDRESS, az as CTF_ORDER_TYPES, n as CancelOrderResult, C as Candlestick, w as CreateOrderInput, aI as DEFAULT_PAGE_SIZE, Y as DFlowOrderContext, D as DFlowQuoteRequest, p as DFlowQuoteResponse, r as DFlowSubmitRequest, q as DFlowSubmitResponse, J as EventSortField, E as EventStatus, N as EventSummary, aq as HttpMethod, j as ListCandlesticksParams, L as ListEventsParams, f as ListMarketTradesParams, l as ListOrdersParams, o as ListTradesParams, I as MarketOutcome, H as MarketResult, M as MarketStatus, Q as MarketSummary, av as NEG_RISK_CTF_EXCHANGE_ADDRESS, aA as ORDER_TYPE, aF as OrderMessage, X as OrderSide, V as OrderStatus, O as Orderbook, K as OrderbookLevel, ax as POLYGON_CHAIN_ID, as as PolymarketL2Headers, ar as PolymarketL2HeadersInput, Z as PolymarketOrderType, k as PositionsResponse, P as PredictClient, c as PredictEvent, e as PredictMarket, m as PredictOrder, b as PredictPage, U as PredictPosition, F as PredictTag, g as PredictTrade, a as PredictWsClient, z as PredictWsClientConfig, h as PriceHistoryRange, i as PriceHistoryResponse, R as PricePoint, A as ProviderMeta, d as ProviderSource, ae as ResolveEventsParamsInput, aB as SIDE, G as SettlementSource, aH as SignedOrder, S as SimilarEventsParams, af as TagSlugSelection, T as TradeType, aw as USDC_ADDRESS, _ as WsChannel, $ as WsChannelEvent, a0 as WsClientMessage, W as WsConnectionStatus, s as WsDataMessage, a6 as WsErrorCode, a7 as WsErrorMessage, u as WsOrderbookEvent, a2 as WsPingMessage, a4 as WsPongMessage, t as WsPriceEvent, a3 as WsServerMessage, a1 as WsSubscribeMessage, a5 as WsSubscribedMessage, v as WsTradeEvent, am as buildClobAuthMessage, ay as buildCtfExchangeDomain, aC as buildOrderMessage, ao as buildPolymarketL2Headers, aD as buildSignedOrder, x as createPredictClient, y as createPredictWsClient, ap as derivePolymarketApiKey, a8 as eventQueryKey, a9 as fetchEvent, ad as fetchEventsPage, ah as fetchMarket, an as hmacSha256Base64, ac as infiniteEventsQueryKey, ag as marketQueryKey, ab as resolveEventsParams, aa as resolveTagSlug } from './server-DlSG7h_v.mjs';
-import '@tanstack/react-query';
+/**
+ * Domain types for the prediction-server REST API.
+ *
+ * Mirrors: github.com/liberfi-io/prediction-server/internal/domain
+ */
+/** Upstream data provider that produced a domain object. */
+type ProviderSource = "dflow" | "polymarket";
+/**
+ * Provider-specific metadata attached to every domain aggregate.
+ * Keys are namespaced field paths, e.g. "polymarket.conditionId" or "dflow.yesMint".
+ * Values are raw JSON-decoded values.
+ */
+type ProviderMeta = Record<string, unknown>;
+/** Provider-sourced label attached to an Event. */
+interface PredictTag {
+    slug: string;
+    label: string;
+    source: ProviderSource;
+    provider_meta?: ProviderMeta;
+}
+/** Lifecycle status of a prediction event (normalised across all providers). */
+type EventStatus = "pending" | "open" | "closed" | "voided";
+/** Settlement / resolution data source for an event. */
+interface SettlementSource {
+    url: string;
+    name?: string;
+}
+/** Root aggregate for a prediction event from the prediction-server API. */
+interface PredictEvent {
+    /** Internal database surrogate key (absent when not yet persisted). */
+    id?: number;
+    /**
+     * Canonical business key shared across all providers.
+     * - DFlow:      ticker (e.g. "KXBTCD-25FEB-T68000")
+     * - Polymarket: slug   (e.g. "will-trump-win-2024")
+     */
+    slug: string;
+    title: string;
+    subtitle?: string;
+    description?: string;
+    image_url?: string;
+    status: EventStatus;
+    /** ISO 8601 timestamp; absent if the provider does not supply it. */
+    start_at?: string;
+    end_at?: string;
+    created_at?: string;
+    updated_at?: string;
+    /** Provider-sourced labels for display only. */
+    tags?: PredictTag[];
+    /** All values are USD amounts. */
+    volume?: number;
+    volume_24h?: number;
+    liquidity?: number;
+    open_interest?: number;
+    settlement_sources?: SettlementSource[];
+    /** Nested markets; omitted when the request used `with_markets=false`. */
+    markets?: PredictMarket[];
+    source: ProviderSource;
+    provider_meta?: ProviderMeta;
+}
+/** Lifecycle status of a prediction market (normalised across all providers). */
+type MarketStatus = "pending" | "open" | "closed" | "voided";
+/** Final resolution of a closed market. Empty string means unresolved. */
+type MarketResult = "yes" | "no" | "voided" | "";
+/** One possible outcome in a binary (or multi-outcome) prediction market. */
+interface MarketOutcome {
+    /** Display name, e.g. "Yes" or "No". */
+    label: string;
+    /** Current implied probability [0, 1]. */
+    price?: number;
+    best_bid?: number;
+    best_ask?: number;
+}
+/** Tradeable prediction outcome within an Event. */
+interface PredictMarket {
+    id?: number;
+    event_id?: number;
+    slug: string;
+    event_slug: string;
+    question: string;
+    description?: string;
+    image_url?: string;
+    /** Resolution/settlement rules in order. */
+    rules?: string[];
+    status: MarketStatus;
+    result?: MarketResult;
+    start_at?: string;
+    end_at?: string;
+    expires_at?: string;
+    closed_at?: string;
+    created_at?: string;
+    updated_at?: string;
+    /** Always present; binary markets have exactly 2 outcomes (YES at [0], NO at [1]). */
+    outcomes: MarketOutcome[];
+    volume?: number;
+    volume_24h?: number;
+    liquidity?: number;
+    open_interest?: number;
+    source: ProviderSource;
+    provider_meta?: ProviderMeta;
+}
+/** Generic paginated result set returned by the prediction-server list endpoints. */
+interface PredictPage<T> {
+    items: T[];
+    next_cursor?: string;
+    has_more?: boolean;
+    limit?: number;
+    /** Not all backends support total count. */
+    total?: number;
+}
+/** Valid sort fields accepted by `GET /api/v1/events`. */
+type EventSortField = "volume" | "volume_24h" | "liquidity" | "open_interest" | "end_at" | "start_at" | "created_at";
+/** Query parameters for `listEvents`. All fields are optional. */
+interface ListEventsParams {
+    /** Page size. Server default: 20. */
+    limit?: number;
+    /** Opaque pagination cursor returned by the previous page's `next_cursor`. */
+    cursor?: string;
+    /** Filter by event lifecycle status. */
+    status?: EventStatus;
+    /** Filter by upstream provider. */
+    source?: ProviderSource;
+    /** Unified navigation tag slug (e.g. "politics", "sports"). */
+    tag_slug?: string;
+    /** Full-text search query. */
+    search?: string;
+    /** Field to sort by. */
+    sort_by?: EventSortField;
+    /** When `true`, sort ascending. Defaults to descending. */
+    sort_asc?: boolean;
+    /**
+     * When `false`, markets are omitted from each event for lighter payloads.
+     * Defaults to `true` on the server.
+     */
+    with_markets?: boolean;
+}
+/** Single price level in an order book. */
+interface OrderbookLevel {
+    price: number;
+    size: number;
+}
+/** Aggregated order book for a market. */
+interface Orderbook {
+    market_id: string;
+    /** Sorted by price descending. */
+    bids: OrderbookLevel[];
+    /** Sorted by price ascending. */
+    asks: OrderbookLevel[];
+    /** best_ask − best_bid; absent when either side is empty. */
+    spread?: number;
+}
+/** On-chain trade type. */
+type TradeType = "TRADE" | "SPLIT" | "MERGE" | "REDEEM" | "REWARD" | "CONVERSION" | "MAKER_REBATE" | "REFERRAL_REWARD";
+/** Lightweight event summary embedded in a trade. */
+interface EventSummary {
+    slug: string;
+    title: string;
+    image_url?: string;
+    status: EventStatus;
+}
+/** Lightweight market summary embedded in a trade. */
+interface MarketSummary {
+    slug: string;
+    question: string;
+    status: MarketStatus;
+}
+/** A single trade record. */
+interface PredictTrade {
+    id: string;
+    source: ProviderSource;
+    side?: string;
+    outcome?: string;
+    outcome_index?: number;
+    price?: number;
+    size: number;
+    usd_size?: number;
+    /** Unix seconds. */
+    timestamp: number;
+    tx_hash?: string;
+    wallet?: string;
+    type: TradeType;
+    event?: EventSummary;
+    market?: MarketSummary;
+    provider_meta?: ProviderMeta;
+}
+/** Query parameters for `GET /api/v1/markets/{slug}/trades`. */
+interface ListMarketTradesParams {
+    source: ProviderSource;
+    limit?: number;
+    cursor?: string;
+    /** Filter by side: `"BUY"` or `"SELL"`. */
+    side?: string;
+}
+/** Query parameters for `GET /api/v1/trades` (by wallet). */
+interface ListTradesParams {
+    /** Provider source. Omit to aggregate all providers. */
+    source?: ProviderSource;
+    wallet: string;
+    limit?: number;
+    cursor?: string;
+    /** Comma-separated trade types. */
+    type?: string;
+    side?: string;
+}
+/** A single price-history data point. */
+interface PricePoint {
+    /** Unix seconds. */
+    t: number;
+    /** Price [0, 1]. */
+    p: number;
+}
+/** Response from `GET /api/v1/markets/{slug}/price-history`. */
+interface PriceHistoryResponse {
+    points: PricePoint[];
+}
+/** Accepted values for the `range` query parameter. */
+type PriceHistoryRange = "1d" | "1w" | "1m" | "all";
+/** OHLCV candlestick data point. */
+interface Candlestick {
+    timestamp: string;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    volume: number;
+}
+/** Query parameters for `GET /api/v1/markets/{slug}/candlesticks`. */
+interface ListCandlesticksParams {
+    /** Candle interval (e.g. `"1m"`, `"5m"`, `"1h"`, `"1d"`). Default: `"1h"`. */
+    interval?: string;
+    /** Number of candles. Default: 100. */
+    limit?: number;
+}
+/** Query parameters for `GET /api/v1/events/{slug}/similar`. */
+interface SimilarEventsParams {
+    /** Number of results (default 5, max 20). */
+    limit?: number;
+    /** When true, only return events from the same provider. */
+    same_source?: boolean;
+}
+/** A single user position in a prediction market. */
+interface PredictPosition {
+    source: ProviderSource;
+    side: string;
+    size: number;
+    avg_price?: number;
+    current_price?: number;
+    current_value?: number;
+    initial_value?: number;
+    pnl?: number;
+    pnl_percent?: number;
+    realized_pnl?: number;
+    redeemable: boolean;
+    event?: PredictEvent;
+    market?: PredictMarket;
+    provider_meta?: ProviderMeta;
+}
+/** Response from `GET /api/v1/positions`. */
+interface PositionsResponse {
+    user: string;
+    positions: PredictPosition[];
+}
+/** Response from `GET /api/v1/balance`. */
+interface BalanceResponse {
+    user: string;
+    source: ProviderSource;
+    /** Token symbol (e.g. "USDC"). */
+    token: string;
+    /** Human-readable balance (e.g. "125.50"). */
+    balance: string;
+    /** Raw balance in smallest unit (e.g. "125500000"). */
+    raw_balance: string;
+    /** Token decimals (e.g. 6 for USDC). */
+    decimals: number;
+}
+/** Lifecycle status of a user order. */
+type OrderStatus = "live" | "matched" | "cancelled" | "invalid" | "submitted" | "pending" | "open" | "pending_close" | "closed" | "failed" | "expired";
+/** Order direction. */
+type OrderSide = "BUY" | "SELL";
+/** A single user order record. */
+interface PredictOrder {
+    id: string;
+    source: ProviderSource;
+    status: OrderStatus;
+    market_id?: string;
+    asset_id?: string;
+    side?: OrderSide;
+    outcome?: string;
+    price?: string;
+    original_size?: string;
+    size_matched?: string;
+    in_amount?: string;
+    out_amount?: string;
+    order_type?: string;
+    /** Unix seconds. */
+    created_at?: number;
+    expires_at?: number;
+    provider_meta?: ProviderMeta;
+}
+/** Query parameters for `GET /api/v1/orders`. */
+interface ListOrdersParams {
+    /** Provider source. Omit to aggregate all providers. */
+    source?: ProviderSource;
+    wallet_address?: string;
+    market_id?: string;
+    asset_id?: string;
+    next_cursor?: string;
+}
+/** Result of `DELETE /api/v1/orders/{id}`. */
+interface CancelOrderResult {
+    cancelled: string[];
+    not_cancelled: Record<string, string>;
+}
+/** Request body for `POST /api/v1/orders/dflow/quote`. */
+interface DFlowQuoteRequest {
+    inputMint: string;
+    outputMint: string;
+    amount: string;
+    userPublicKey: string;
+    slippageBps?: number;
+}
+/** Raw upstream response from DFlow quote (transparent passthrough). */
+type DFlowQuoteResponse = Record<string, unknown>;
+/** Context stored alongside a DFlow order for later enrichment. */
+interface DFlowOrderContext {
+    user_public_key: string;
+    input_mint: string;
+    output_mint: string;
+    amount: string;
+    price: string;
+    side: string;
+    outcome: string;
+    market_slug: string;
+    slippage_bps: number;
+}
+/** Request body for `POST /api/v1/orders/dflow/submit`. */
+interface DFlowSubmitRequest {
+    signedTransaction: string;
+    orderContext: DFlowOrderContext;
+}
+/** Response from `POST /api/v1/orders/dflow/submit`. */
+interface DFlowSubmitResponse {
+    signature: string;
+    status: OrderStatus;
+}
+/** Order type for Polymarket CLOB. */
+type PolymarketOrderType = "GTC" | "FOK" | "GTD" | "FAK";
+/** Input for creating a Polymarket limit order. */
+interface CreateOrderInput {
+    /** Token ID (outcome asset ID) from market provider_meta. */
+    tokenId: string;
+    /** Price in range [0.01, 0.99]. */
+    price: number;
+    /** Order size in USDC. */
+    size: number;
+    side: OrderSide;
+    orderType?: PolymarketOrderType;
+    /** Minimum tick size for this market (from Polymarket gamma API). */
+    tickSize: "0.1" | "0.01" | "0.001" | "0.0001";
+    /** Whether this is a neg-risk market (uses different exchange contract). */
+    negRisk?: boolean;
+    /** Expiration timestamp (Unix seconds). Required for GTD orders. */
+    expiration?: number;
+    /**
+     * The funder address that holds the USDC (proxy/Gnosis Safe wallet).
+     * Defaults to the signer address when not provided.
+     */
+    funderAddress?: string;
+}
+/** WebSocket subscription channel. */
+type WsChannel = "orderbook" | "prices" | "trades";
+/** WebSocket connection lifecycle status. */
+type WsConnectionStatus = "connecting" | "connected" | "disconnected" | "reconnecting";
+/**
+ * Full orderbook snapshot pushed via the `orderbook` channel.
+ * Always a complete replacement — no delta merging required.
+ */
+interface WsOrderbookEvent {
+    market_slug: string;
+    bids: OrderbookLevel[];
+    asks: OrderbookLevel[];
+    spread?: number;
+}
+/** Latest bid/ask prices pushed via the `prices` channel. */
+interface WsPriceEvent {
+    market_slug: string;
+    yes_bid?: number;
+    yes_ask?: number;
+    no_bid?: number;
+    no_ask?: number;
+    spread?: number;
+}
+/** Single trade execution pushed via the `trades` channel. */
+interface WsTradeEvent {
+    market_slug: string;
+    trade_id?: string;
+    side: string;
+    price: number;
+    size: number;
+    outcome?: string;
+}
+/** Union of all channel data payloads. */
+type WsChannelEvent = WsOrderbookEvent | WsPriceEvent | WsTradeEvent;
+/** Subscribe or unsubscribe message sent to the server. */
+interface WsSubscribeMessage {
+    type: "subscribe" | "unsubscribe";
+    channels: WsChannel[];
+    market_slugs: string[];
+}
+/** Client ping (application-level keepalive). */
+interface WsPingMessage {
+    type: "ping";
+}
+/** Union of all messages the client can send. */
+type WsClientMessage = WsSubscribeMessage | WsPingMessage;
+/** Pong response to a client ping. */
+interface WsPongMessage {
+    type: "pong";
+}
+/** Subscription confirmation. */
+interface WsSubscribedMessage {
+    type: "subscribed";
+    channels: WsChannel[];
+    market_slugs: string[];
+}
+/** Error codes the server may return. */
+type WsErrorCode = "invalid_message" | "market_not_found" | "provider_unavailable" | "provider_reconnecting";
+/** Error message from the server. */
+interface WsErrorMessage {
+    type: "error";
+    code: WsErrorCode;
+    message: string;
+}
+/** Data message carrying a channel event payload. */
+interface WsDataMessage<T extends WsChannelEvent = WsChannelEvent> {
+    channel: WsChannel;
+    market_slug: string;
+    data: T;
+    ts: number;
+}
+/** Union of all messages the server can send. */
+type WsServerMessage = WsPongMessage | WsSubscribedMessage | WsErrorMessage | WsDataMessage;
+
+/**
+ * HTTP client for the prediction-server REST API.
+ *
+ * Covers all prediction, market, order, position, and trading endpoints.
+ *
+ * @example
+ * ```ts
+ * const client = new PredictClient("https://api.example.com");
+ * const page = await client.listEvents({ status: "open", limit: 20 });
+ * const event = await client.getEvent("will-trump-win-2024");
+ * const market = await client.getMarket("will-trump-win-2024-yes");
+ * ```
+ */
+declare class PredictClient {
+    private readonly endpoint;
+    constructor(endpoint: string);
+    /**
+     * List prediction events with optional filtering, sorting, and pagination.
+     *
+     * Maps to `GET /api/v1/events`.
+     *
+     * @param params - Optional query parameters (filter, sort, pagination).
+     * @returns A paginated page of events.
+     */
+    listEvents(params?: ListEventsParams): Promise<PredictPage<PredictEvent>>;
+    /**
+     * Fetch a single prediction event by its slug.
+     *
+     * Maps to `GET /api/v1/events/:slug?source=...`.
+     *
+     * @param slug - Canonical event slug (e.g. "will-trump-win-2024" for Polymarket
+     *               or "KXBTCD-25FEB-T68000" for DFlow).
+     * @param source - Upstream provider (`"dflow"` or `"polymarket"`).
+     * @returns The matching event.
+     * @throws When the server responds with 404 or any other non-2xx status.
+     */
+    getEvent(slug: string, source?: ProviderSource): Promise<PredictEvent>;
+    /**
+     * Fetch events similar to the given slug.
+     *
+     * Maps to `GET /api/v1/events/:slug/similar?source=...`.
+     */
+    getSimilarEvents(slug: string, source: ProviderSource, params?: SimilarEventsParams): Promise<PredictEvent[]>;
+    /**
+     * Fetch a single prediction market by its slug.
+     *
+     * Maps to `GET /api/v1/markets/:slug?source=...`.
+     *
+     * @param slug - Canonical market slug.
+     * @param source - Upstream provider (`"dflow"` or `"polymarket"`).
+     * @returns The matching market.
+     * @throws When the server responds with 404 or any other non-2xx status.
+     */
+    getMarket(slug: string, source?: ProviderSource): Promise<PredictMarket>;
+    /** Maps to `GET /api/v1/markets/:slug/orderbook?source=...`. */
+    getOrderbook(slug: string, source: ProviderSource): Promise<Orderbook>;
+    /** Maps to `GET /api/v1/markets/:slug/trades?source=...`. */
+    listMarketTrades(slug: string, params: ListMarketTradesParams): Promise<PredictPage<PredictTrade>>;
+    /** Maps to `GET /api/v1/markets/:slug/price-history?source=...&range=...`. */
+    getPriceHistory(slug: string, source: ProviderSource, range?: PriceHistoryRange): Promise<PriceHistoryResponse>;
+    /** Maps to `GET /api/v1/markets/:slug/candlesticks?interval=...&limit=...`. */
+    listCandlesticks(slug: string, params?: ListCandlesticksParams): Promise<Candlestick[]>;
+    /**
+     * Maps to `GET /api/v1/positions?source=...&user=...`.
+     *
+     * @param user - Wallet address.
+     * @param source - Provider source. Omit to aggregate all providers.
+     */
+    getPositions(user: string, source?: ProviderSource): Promise<PositionsResponse>;
+    /**
+     * Get the on-chain USDC balance for a wallet.
+     *
+     * Maps to `GET /api/v1/balance?source=...&user=...`.
+     *
+     * @param source - Provider source (`"dflow"` for Solana, `"polymarket"` for Polygon).
+     * @param user - Wallet address.
+     */
+    getBalance(source: ProviderSource, user: string): Promise<BalanceResponse>;
+    /** Maps to `GET /api/v1/orders?source=...&wallet_address=...`. */
+    listOrders(params: ListOrdersParams): Promise<PredictPage<PredictOrder>>;
+    /** Maps to `GET /api/v1/orders/:id?source=...`. */
+    getOrder(id: string, source: ProviderSource): Promise<PredictOrder>;
+    /** Maps to `DELETE /api/v1/orders/:id?source=...`. */
+    cancelOrder(id: string, source: ProviderSource): Promise<CancelOrderResult>;
+    /**
+     * Create a Polymarket limit order via the prediction-server proxy.
+     *
+     * Maps to `POST /api/v1/orders/polymarket`.
+     *
+     * The caller must attach Polymarket CLOB authentication headers:
+     * - `POLY_ADDRESS` — the EVM wallet address.
+     * - `POLY_SIGNATURE` — L1 signature or L2 API key.
+     * - `POLY_TIMESTAMP` — Unix milliseconds string.
+     * - `POLY_NONCE` — credential nonce (use `"0"` for in-session derived creds).
+     *
+     * @param input - Order parameters.
+     * @param headers - Polymarket CLOB auth headers (`POLY_*`).
+     */
+    createPolymarketOrder(input: CreateOrderInput, headers: Record<string, string>): Promise<PredictOrder>;
+    /** Maps to `POST /api/v1/orders/dflow/quote`. */
+    createDFlowQuote(body: DFlowQuoteRequest): Promise<DFlowQuoteResponse>;
+    /** Maps to `POST /api/v1/orders/dflow/submit`. */
+    submitDFlowTransaction(body: DFlowSubmitRequest): Promise<DFlowSubmitResponse>;
+    /** Maps to `GET /api/v1/trades?source=...&wallet=...`. */
+    listTrades(params: ListTradesParams): Promise<PredictPage<PredictTrade>>;
+}
+/**
+ * Factory function for `PredictClient`.
+ *
+ * @param endpoint - Base URL of the prediction-server, without a trailing slash.
+ */
+declare function createPredictClient(endpoint: string): PredictClient;
+
+/**
+ * PredictWsClient — WebSocket client for prediction-server real-time data.
+ *
+ * Connects to `GET /api/v1/ws` (RFC 6455) and supports three channels:
+ * `orderbook`, `prices`, and `trades`.
+ *
+ * Features:
+ * - Auto-reconnect with exponential backoff
+ * - Application-level ping/pong keepalive
+ * - Subscription state tracking with automatic restore after reconnect
+ * - Event-emitter pattern for typed message dispatch
+ */
+
+/** Configuration for `PredictWsClient`. */
+interface PredictWsClientConfig {
+    /** Full WebSocket URL, e.g. `"wss://api.example.com/api/v1/ws"`. */
+    wsUrl: string;
+    /** Connect immediately on construction. Default: `true`. */
+    autoConnect?: boolean;
+    /** Reconnect automatically on unexpected close. Default: `true`. */
+    autoReconnect?: boolean;
+    /** Base delay (ms) for exponential backoff. Default: `1000`. */
+    reconnectIntervalBase?: number;
+    /** Maximum reconnect delay (ms). Default: `30000`. */
+    reconnectMaxInterval?: number;
+    /** Interval (ms) between application-level pings. Default: `30000`. */
+    pingInterval?: number;
+    /**
+     * How long (ms) to wait for a pong after sending a ping before
+     * considering the connection dead. Default: `10000`.
+     * Must be less than `pingInterval`.
+     */
+    pongTimeout?: number;
+}
+type EventCallback<T = unknown> = (data: T) => void;
+interface EventListeners {
+    connect: EventCallback<void>[];
+    disconnect: EventCallback<{
+        code?: number;
+        reason?: string;
+    }>[];
+    reconnecting: EventCallback<{
+        attempt: number;
+        delay: number;
+    }>[];
+    error: EventCallback<{
+        code: WsErrorCode;
+        message: string;
+    }>[];
+    status: EventCallback<WsConnectionStatus>[];
+    subscribed: EventCallback<{
+        channels: WsChannel[];
+        market_slugs: string[];
+    }>[];
+    orderbook: EventCallback<WsDataMessage<WsOrderbookEvent>>[];
+    prices: EventCallback<WsDataMessage<WsPriceEvent>>[];
+    trades: EventCallback<WsDataMessage<WsTradeEvent>>[];
+}
+type WsEventType = keyof EventListeners;
+declare class PredictWsClient {
+    private ws;
+    private readonly wsUrl;
+    private readonly autoReconnect;
+    private readonly reconnectBase;
+    private readonly reconnectMax;
+    private readonly pingMs;
+    private readonly pongTimeoutMs;
+    private status;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private pingTimer;
+    private pongTimer;
+    private shouldReconnect;
+    private listeners;
+    private subs;
+    constructor(config: PredictWsClientConfig);
+    connect(): void;
+    disconnect(): void;
+    /** Disconnect and clear all subscription state and listeners. */
+    destroy(): void;
+    getStatus(): WsConnectionStatus;
+    isConnected(): boolean;
+    /**
+     * Subscribe to one or more channels for the given market slugs.
+     * The server acknowledges with a `subscribed` message.
+     */
+    subscribe(channels: WsChannel[], marketSlugs: string[]): void;
+    /**
+     * Unsubscribe from one or more channels for the given market slugs.
+     */
+    unsubscribe(channels: WsChannel[], marketSlugs: string[]): void;
+    /**
+     * Subscribe to price updates for the given slugs.
+     * Returns an unsubscribe function.
+     */
+    subscribePrices(slugs: string[], onUpdate: (msg: WsDataMessage<WsPriceEvent>) => void): () => void;
+    /**
+     * Subscribe to orderbook snapshots for the given slugs.
+     * Returns an unsubscribe function.
+     */
+    subscribeOrderbook(slugs: string[], onUpdate: (msg: WsDataMessage<WsOrderbookEvent>) => void): () => void;
+    /**
+     * Subscribe to trade events for the given slugs.
+     * Returns an unsubscribe function.
+     */
+    subscribeTrades(slugs: string[], onUpdate: (msg: WsDataMessage<WsTradeEvent>) => void): () => void;
+    /** Register a callback for connection status changes. Returns unsubscribe. */
+    onStatusChange(cb: (status: WsConnectionStatus) => void): () => void;
+    /** Register a callback for server-sent errors. Returns unsubscribe. */
+    onError(cb: (err: {
+        code: WsErrorCode;
+        message: string;
+    }) => void): () => void;
+    on<T extends WsEventType>(event: T, callback: EventListeners[T][number]): () => void;
+    off<T extends WsEventType>(event: T, callback: EventListeners[T][number]): void;
+    private emit;
+    private send;
+    private setStatus;
+    private handleMessage;
+    private scheduleReconnect;
+    private clearReconnectTimer;
+    private restoreSubscriptions;
+    private startPing;
+    private stopPing;
+    /**
+     * Start a timer that fires if the server does not reply with pong
+     * within `pongTimeoutMs`. On timeout the socket is closed so
+     * the normal reconnect flow kicks in.
+     */
+    private armPongTimeout;
+    private clearPongTimer;
+}
+/**
+ * Factory function for `PredictWsClient`.
+ *
+ * @param config - WebSocket client configuration.
+ */
+declare function createPredictWsClient(config: PredictWsClientConfig): PredictWsClient;
+
+/**
+ * Server-safe pure functions for events query parameters.
+ *
+ * This module contains NO React imports and can be used in Server Components,
+ * route handlers, or any non-browser context.
+ */
+
+/** Default page size for list queries. */
+declare const DEFAULT_PAGE_SIZE = 48;
+/**
+ * Selection emitted by a categories/tag selector widget.
+ * Duplicated here to avoid pulling in UI component barrel into server-only bundles.
+ */
+interface TagSlugSelection {
+    categorySlug: string | null;
+    tagSlug: string | null;
+}
+/**
+ * Resolve a `TagSlugSelection` to a single `tag_slug` string for the API.
+ */
+declare function resolveTagSlug(selection: TagSlugSelection | null | undefined): string | undefined;
+/**
+ * Input accepted by {@link resolveEventsParams}. All fields optional;
+ * defaults match the client-side `useInfiniteEvents` hook's initial state.
+ */
+interface ResolveEventsParamsInput {
+    tagSlugSelection?: TagSlugSelection | null;
+    limit?: number;
+    status?: EventStatus;
+    sort_by?: EventSortField;
+    sort_asc?: boolean;
+    source?: ProviderSource;
+    with_markets?: boolean;
+}
+/**
+ * Build a clean `ListEventsParams` from loose user inputs.
+ *
+ * Server-side `prefetchInfiniteQuery` and client-side `useInfiniteEvents` must
+ * both use this function to guarantee identical query keys.
+ */
+declare function resolveEventsParams(input?: ResolveEventsParamsInput): ListEventsParams;
+/** Stable TanStack Query key for the events infinite query. */
+declare function infiniteEventsQueryKey(params: ListEventsParams): unknown[];
+/**
+ * Fetch a single page of events. Can be used outside of React
+ * (e.g. in Server Components, loaders, or tests).
+ */
+declare function fetchEventsPage(client: PredictClient, params: ListEventsParams): Promise<PredictPage<PredictEvent>>;
+/** Stable TanStack Query key for a single event. */
+declare function eventQueryKey(slug: string, source?: ProviderSource): unknown[];
+/**
+ * Fetch a single event. Can be used outside of React
+ * (e.g. in Server Components, loaders, or tests).
+ */
+declare function fetchEvent(client: PredictClient, slug: string, source?: ProviderSource): Promise<PredictEvent>;
+
+/**
+ * Server-safe pure functions for market query helpers.
+ *
+ * This module contains NO React imports and can be used in Server Components,
+ * route handlers, or any non-browser context.
+ */
+
+/** Stable TanStack Query key for a single market. */
+declare function marketQueryKey(slug: string, source?: ProviderSource): unknown[];
+/**
+ * Fetch function usable outside React (e.g. in loaders or tests).
+ */
+declare function fetchMarket(client: PredictClient, slug: string, source?: ProviderSource): Promise<PredictMarket>;
+
+/**
+ * Polymarket L2 HMAC-SHA256 signing utilities.
+ *
+ * Uses the Web Crypto API (available in all modern browsers and Node ≥18) to
+ * avoid taking a dependency on Node.js `crypto` or any third-party library.
+ *
+ * References:
+ *   https://docs.polymarket.com/#authentication
+ *   https://github.com/Polymarket/clob-client/blob/main/src/headers/index.ts
+ */
+/**
+ * Compute an HMAC-SHA256 signature using the Web Crypto API.
+ *
+ * @param secretBase64 - The signing secret encoded as base64.
+ * @param message      - The plaintext message to sign.
+ * @returns The signature as a base64 string.
+ */
+declare function hmacSha256Base64(secretBase64: string, message: string): Promise<string>;
+/** HTTP method values accepted by Polymarket CLOB. */
+type HttpMethod = "GET" | "DELETE" | "POST" | "PUT";
+interface PolymarketL2HeadersInput {
+    /** L2 API key (from credential exchange). */
+    apiKey: string;
+    /** L2 HMAC secret (base64-encoded). */
+    secret: string;
+    /** L2 passphrase. */
+    passphrase: string;
+    /** HTTP method of the request. */
+    method: HttpMethod;
+    /** Request path without host, e.g. "/order". */
+    requestPath: string;
+    /** Raw JSON request body string; empty string for GET/DELETE. */
+    body?: string;
+}
+interface PolymarketL2Headers {
+    POLY_ADDRESS: string;
+    POLY_SIGNATURE: string;
+    POLY_TIMESTAMP: string;
+    POLY_API_KEY: string;
+    POLY_PASSPHRASE: string;
+}
+/**
+ * Build Polymarket L2 HMAC authentication headers for a CLOB API request.
+ *
+ * The signature is `HMAC-SHA256(secret, timestamp + method + requestPath + body)`.
+ *
+ * @param address - EVM wallet address (owner of the credentials).
+ * @param input   - Credential and request details.
+ * @returns An object containing all required `POLY_*` headers.
+ */
+declare function buildPolymarketL2Headers(address: string, input: PolymarketL2HeadersInput): Promise<PolymarketL2Headers>;
+/** EIP-712 domain used by Polymarket CLOB for L1 authentication. */
+declare const CLOB_AUTH_DOMAIN: {
+    readonly name: "ClobAuthDomain";
+    readonly version: "1";
+    readonly chainId: 137;
+};
+/** EIP-712 types for the `ClobAuth` struct. */
+declare const CLOB_AUTH_TYPES: {
+    readonly ClobAuth: readonly [{
+        readonly name: "address";
+        readonly type: "address";
+    }, {
+        readonly name: "timestamp";
+        readonly type: "string";
+    }, {
+        readonly name: "nonce";
+        readonly type: "uint256";
+    }, {
+        readonly name: "message";
+        readonly type: "string";
+    }];
+};
+interface BuildClobAuthMessageInput {
+    /** EVM wallet address. */
+    address: string;
+    /** Unix seconds string. */
+    timestamp: string;
+    /** Credential nonce. Use `0` for a permanent / deterministic credential. */
+    nonce: number;
+}
+/**
+ * Build the EIP-712 typed data value for a `ClobAuth` message.
+ * The resulting object is passed to `eth_signTypedData_v4`.
+ */
+declare function buildClobAuthMessage(input: BuildClobAuthMessageInput): Record<string, unknown>;
+/**
+ * Exchange an L1 EIP-712 signature for Polymarket L2 API credentials.
+ *
+ * Calls `GET https://clob.polymarket.com/auth/derive-api-key` directly from
+ * the browser (the endpoint has `Access-Control-Allow-Origin: *`).
+ *
+ * @returns The raw API response `{ apiKey, secret, passphrase }`.
+ */
+declare function derivePolymarketApiKey(address: string, signature: string, timestamp: string, nonce: number): Promise<{
+    apiKey: string;
+    secret: string;
+    passphrase: string;
+}>;
+
+/**
+ * Polymarket CTF Exchange order construction utilities.
+ *
+ * Implements EIP-712 signing for `Order` structs on the CTF Exchange and
+ * Neg-Risk CTF Exchange contracts (Polygon mainnet).
+ *
+ * References:
+ *   https://github.com/Polymarket/clob-client/blob/main/src/order-builder/builder.ts
+ *   https://github.com/Polymarket/clob-client/blob/main/src/order-builder/helpers.ts
+ *   https://docs.polymarket.com/#create-order
+ */
+
+/** Polymarket CTF Exchange contract (standard markets). */
+declare const CTF_EXCHANGE_ADDRESS: "0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E";
+/** Polymarket Neg-Risk CTF Exchange contract (neg-risk markets). */
+declare const NEG_RISK_CTF_EXCHANGE_ADDRESS: "0xC5d563A36AE78145C45a50134d48A1215220f80a";
+/** USDC.e (Bridged USDC) on Polygon — the only collateral token on Polymarket. */
+declare const USDC_ADDRESS: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174";
+/** Chain ID for Polygon mainnet. */
+declare const POLYGON_CHAIN_ID = 137;
+/**
+ * Build the EIP-712 domain for the CTF Exchange.
+ *
+ * @param negRisk - When `true`, use the Neg-Risk exchange address.
+ */
+declare function buildCtfExchangeDomain(negRisk?: boolean): {
+    name: string;
+    version: string;
+    chainId: number;
+    verifyingContract: "0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E" | "0xC5d563A36AE78145C45a50134d48A1215220f80a";
+};
+/** EIP-712 type definitions for the Polymarket `Order` struct. */
+declare const CTF_ORDER_TYPES: {
+    readonly Order: readonly [{
+        readonly name: "salt";
+        readonly type: "uint256";
+    }, {
+        readonly name: "maker";
+        readonly type: "address";
+    }, {
+        readonly name: "signer";
+        readonly type: "address";
+    }, {
+        readonly name: "taker";
+        readonly type: "address";
+    }, {
+        readonly name: "tokenId";
+        readonly type: "uint256";
+    }, {
+        readonly name: "makerAmount";
+        readonly type: "uint256";
+    }, {
+        readonly name: "takerAmount";
+        readonly type: "uint256";
+    }, {
+        readonly name: "expiration";
+        readonly type: "uint256";
+    }, {
+        readonly name: "nonce";
+        readonly type: "uint256";
+    }, {
+        readonly name: "feeRateBps";
+        readonly type: "uint256";
+    }, {
+        readonly name: "side";
+        readonly type: "uint8";
+    }, {
+        readonly name: "signatureType";
+        readonly type: "uint8";
+    }];
+};
+/** Order type enum matching CTFExchange.sol. */
+declare const ORDER_TYPE: {
+    readonly GTC: 0;
+    readonly FOK: 1;
+    readonly GTD: 2;
+    readonly FAK: 3;
+};
+/** Side enum matching CTFExchange.sol (0 = BUY, 1 = SELL). */
+declare const SIDE: {
+    readonly BUY: 0;
+    readonly SELL: 1;
+};
+interface BuildOrderMessageInput extends CreateOrderInput {
+    /** Signer / owner address. */
+    signerAddress: string;
+    /** Signature type (0 = EOA, 1 = Magic, 2 = Poly Proxy). */
+    signatureType: 0 | 1 | 2;
+}
+interface OrderMessage {
+    salt: string;
+    maker: string;
+    signer: string;
+    taker: string;
+    tokenId: string;
+    makerAmount: string;
+    takerAmount: string;
+    expiration: string;
+    nonce: string;
+    feeRateBps: string;
+    side: number;
+    signatureType: number;
+}
+/**
+ * Build the EIP-712 typed data value for a Polymarket limit order.
+ *
+ * All amounts are in micro-USDC (1 USDC = 1 000 000).
+ *
+ * For a BUY order:
+ *   - `makerAmount` = USDC spent (cost = size × price)
+ *   - `takerAmount` = shares received (= size)
+ *
+ * For a SELL order:
+ *   - `makerAmount` = shares sold (= size)
+ *   - `takerAmount` = USDC received (cost = size × price)
+ */
+declare function buildOrderMessage(input: BuildOrderMessageInput): OrderMessage;
+interface SignedOrder extends OrderMessage {
+    signature: string;
+    orderType: string;
+}
+interface BuildSignedOrderInput extends BuildOrderMessageInput {
+    /** Hex signature returned by `eth_signTypedData_v4`. */
+    signature: string;
+}
+/**
+ * Construct the final signed order payload to submit to the Polymarket CLOB
+ * (via prediction-server proxy `POST /api/v1/orders/polymarket`).
+ */
+declare function buildSignedOrder(input: BuildSignedOrderInput): SignedOrder;
+
+export { type BalanceResponse, type BuildClobAuthMessageInput, type BuildOrderMessageInput, type BuildSignedOrderInput, CLOB_AUTH_DOMAIN, CLOB_AUTH_TYPES, CTF_EXCHANGE_ADDRESS, CTF_ORDER_TYPES, type CancelOrderResult, type Candlestick, type CreateOrderInput, DEFAULT_PAGE_SIZE, type DFlowOrderContext, type DFlowQuoteRequest, type DFlowQuoteResponse, type DFlowSubmitRequest, type DFlowSubmitResponse, type EventSortField, type EventStatus, type EventSummary, type HttpMethod, type ListCandlesticksParams, type ListEventsParams, type ListMarketTradesParams, type ListOrdersParams, type ListTradesParams, type MarketOutcome, type MarketResult, type MarketStatus, type MarketSummary, NEG_RISK_CTF_EXCHANGE_ADDRESS, ORDER_TYPE, type OrderMessage, type OrderSide, type OrderStatus, type Orderbook, type OrderbookLevel, POLYGON_CHAIN_ID, type PolymarketL2Headers, type PolymarketL2HeadersInput, type PolymarketOrderType, type PositionsResponse, PredictClient, type PredictEvent, type PredictMarket, type PredictOrder, type PredictPage, type PredictPosition, type PredictTag, type PredictTrade, PredictWsClient, type PredictWsClientConfig, type PriceHistoryRange, type PriceHistoryResponse, type PricePoint, type ProviderMeta, type ProviderSource, type ResolveEventsParamsInput, SIDE, type SettlementSource, type SignedOrder, type SimilarEventsParams, type TagSlugSelection, type TradeType, USDC_ADDRESS, type WsChannel, type WsChannelEvent, type WsClientMessage, type WsConnectionStatus, type WsDataMessage, type WsErrorCode, type WsErrorMessage, type WsOrderbookEvent, type WsPingMessage, type WsPongMessage, type WsPriceEvent, type WsServerMessage, type WsSubscribeMessage, type WsSubscribedMessage, type WsTradeEvent, buildClobAuthMessage, buildCtfExchangeDomain, buildOrderMessage, buildPolymarketL2Headers, buildSignedOrder, createPredictClient, createPredictWsClient, derivePolymarketApiKey, eventQueryKey, fetchEvent, fetchEventsPage, fetchMarket, hmacSha256Base64, infiniteEventsQueryKey, marketQueryKey, resolveEventsParams, resolveTagSlug };