fix: resolve outcome aliases in fetchOrderBook

Author: realfishsam

changelog.md

@@ -2,6 +2,12 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.43.13] - 2026-05-24
+
+### Fixed
+
+- **fetchOrderBook**: `params.outcome` now accepts `"yes"`/`"no"` outcome aliases when the first argument is a market ID. The alias is resolved to the venue's actual outcome token ID before fetching live or historical order books, while raw outcome token IDs continue to work unchanged.
+
 ## [2.43.12] - 2026-05-23
 
 ### Fixed

core/src/BaseExchange.ts

@@ -174,6 +174,11 @@ export interface FetchOrderBookParams {
     /** Outcome side: 'yes' or 'no'. Required for exchanges like Limitless
      *  where the API returns a single orderbook per market. */
     side?: 'yes' | 'no';
+    /** Outcome alias: 'yes' or 'no', or an outcome token ID. When set,
+     *  the first argument is treated as a market ID and this value selects
+     *  which outcome's order book to fetch. Accepts the literal strings
+     *  'yes'/'no' (resolved via a market lookup) or a raw outcome token ID. */
+    outcome?: string;
     /** Unix timestamp (ms) — fetch a historical snapshot at or before this
      *  time, or the start of a range when combined with `until` (hosted API only). */
     since?: number;
@@ -816,6 +821,75 @@ export abstract class PredictionMarketExchange {
         return markets[0];
     }
 
+    private cacheMarketLookup(market: UnifiedMarket): void {
+        this.markets[market.marketId] = market;
+        if (market.slug) {
+            this.marketsBySlug[market.slug] = market;
+        }
+    }
+
+    private marketMatchesIdentifier(market: UnifiedMarket, id: string): boolean {
+        return market.marketId === id
+            || market.slug === id
+            || market.contractAddress === id
+            || (market as any).id === id;
+    }
+
+    private getCachedMarketForOutcomeAlias(id: string): UnifiedMarket | undefined {
+        const direct = this.markets[id] ?? this.marketsBySlug[id];
+        if (direct && this.marketMatchesIdentifier(direct, id)) return direct;
+        return Object.values(this.markets).find((market) => this.marketMatchesIdentifier(market, id));
+    }
+
+    private async fetchMarketForOutcomeAlias(id: string): Promise<UnifiedMarket> {
+        const cached = this.getCachedMarketForOutcomeAlias(id);
+        if (cached) return cached;
+
+        for (const params of [{ marketId: id }, { slug: id }]) {
+            const markets = await this.fetchMarkets(params);
+            const exact = markets.find((market) => this.marketMatchesIdentifier(market, id));
+            const market = exact ?? (markets.length === 1 ? markets[0] : undefined);
+            if (market) {
+                this.cacheMarketLookup(market);
+                return market;
+            }
+        }
+
+        throw new MarketNotFound(id, this.name);
+    }
+
+    /**
+     * Resolve an outcome alias ('yes'/'no') to an actual outcome token ID.
+     * When params.outcome is set, treats `id` as a market ID, looks up the
+     * market, and returns the resolved outcome token ID plus cleaned params.
+     * When params.outcome is already a token ID (not 'yes'/'no'), returns it
+     * directly. When params.outcome is not set, returns `id` unchanged.
+     */
+    protected async resolveOutcomeAlias(
+        id: string,
+        params?: FetchOrderBookParams,
+    ): Promise<{ outcomeId: string; params?: FetchOrderBookParams }> {
+        if (!params?.outcome) return { outcomeId: id, params };
+
+        const outcome = String(params.outcome);
+        const alias = outcome.toLowerCase();
+        const { outcome: _, ...rest } = params;
+
+        if (alias === 'yes' || alias === 'no') {
+            const market = await this.fetchMarketForOutcomeAlias(id);
+            const selected = alias === 'yes' ? market.yes : market.no;
+            if (!selected) {
+                throw new Error(
+                    `Market "${id}" has no '${alias}' outcome on ${this.name}`,
+                );
+            }
+            return { outcomeId: selected.outcomeId, params: rest };
+        }
+
+        // outcome is already a raw token ID — use it directly
+        return { outcomeId: outcome, params: rest };
+    }
+
     // ----------------------------------------------------------------------------
     // Implementation methods (to be overridden by exchanges)
     // ----------------------------------------------------------------------------

core/src/exchanges/baozi/index.ts

@@ -125,6 +125,9 @@ export class BaoziExchange extends PredictionMarketExchange {
     }
 
     async fetchOrderBook(outcomeId: string, _limit?: number, _params?: Record<string, any>): Promise<OrderBook> {
+        const resolved = await this.resolveOutcomeAlias(outcomeId, _params);
+        outcomeId = resolved.outcomeId;
+        _params = resolved.params;
         const rawMarket = await this.fetcher.fetchRawOrderBook(outcomeId);
         return this.normalizer.normalizeOrderBook(rawMarket, outcomeId);
     }

core/src/exchanges/gemini-titan/index.ts

@@ -107,6 +107,9 @@ export class GeminiTitanExchange extends PredictionMarketExchange {
     }
 
     async fetchOrderBook(outcomeId: string, _limit?: number, _params?: Record<string, any>): Promise<OrderBook> {
+        const resolved = await this.resolveOutcomeAlias(outcomeId, _params);
+        outcomeId = resolved.outcomeId;
+        _params = resolved.params;
         const { instrumentSymbol } = fromOutcomeId(outcomeId);
         const raw = await this.fetcher.fetchRawOrderBook(instrumentSymbol);
         if (!raw) {

core/src/exchanges/hyperliquid/index.ts

@@ -129,6 +129,9 @@ export class HyperliquidExchange extends PredictionMarketExchange {
     }
 
     async fetchOrderBook(outcomeId: string, _limit?: number, _params?: Record<string, any>): Promise<OrderBook> {
+        const resolved = await this.resolveOutcomeAlias(outcomeId, _params);
+        outcomeId = resolved.outcomeId;
+        _params = resolved.params;
         const raw = await this.fetcher.fetchRawOrderBook(outcomeId);
         return this.normalizer.normalizeOrderBook(raw, outcomeId);
     }

core/src/exchanges/kalshi/index.ts

@@ -195,6 +195,9 @@ export class KalshiExchange extends PredictionMarketExchange {
     }
 
     async fetchOrderBook(outcomeId: string, _limit?: number, _params?: Record<string, any>): Promise<OrderBook> {
+        const resolved = await this.resolveOutcomeAlias(outcomeId, _params);
+        outcomeId = resolved.outcomeId;
+        _params = resolved.params;
         const raw = await this.fetcher.fetchRawOrderBook(outcomeId);
         return this.normalizer.normalizeOrderBook(raw, outcomeId);
     }

core/src/exchanges/limitless/index.ts

@@ -202,6 +202,9 @@ export class LimitlessExchange extends PredictionMarketExchange {
     }
 
     async fetchOrderBook(outcomeId: string, limit?: number, params?: Record<string, any>): Promise<OrderBook> {
+        const resolved = await this.resolveOutcomeAlias(outcomeId, params);
+        outcomeId = resolved.outcomeId;
+        params = resolved.params;
         const slug = await this.resolveSlug(outcomeId);
         const rawOrderBook = await this.fetcher.fetchRawOrderBook!(slug);
         const orderBook = this.normalizer.normalizeOrderBook!(rawOrderBook as any, outcomeId);

core/src/exchanges/mock/index.ts

@@ -318,6 +318,8 @@ export class MockExchange extends PredictionMarketExchange {
     }
 
     override async fetchOrderBook(id: string, _limit?: number, _params?: Record<string, any>): Promise<OrderBook> {
+        const resolved = await this.resolveOutcomeAlias(id, _params);
+        id = resolved.outcomeId;
         const f = new SeededRng(id);
         const midPrice = round(f.float(0.1, 0.9), 3);
         const spread = round(f.float(0.005, 0.03), 3);

core/src/exchanges/myriad/index.ts

@@ -110,6 +110,9 @@ export class MyriadExchange extends PredictionMarketExchange {
     }
 
     async fetchOrderBook(outcomeId: string, _limit?: number, _params?: Record<string, any>): Promise<OrderBook> {
+        const resolved = await this.resolveOutcomeAlias(outcomeId, _params);
+        outcomeId = resolved.outcomeId;
+        _params = resolved.params;
         const parts = outcomeId.split(':');
         if (parts.length >= 3) {
             const [networkId, marketId, oid] = parts;

core/src/exchanges/opinion/index.ts

@@ -208,6 +208,9 @@ export class OpinionExchange extends PredictionMarketExchange {
     }
 
     async fetchOrderBook(outcomeId: string, _limit?: number, _params?: Record<string, any>): Promise<OrderBook> {
+        const resolved = await this.resolveOutcomeAlias(outcomeId, _params);
+        outcomeId = resolved.outcomeId;
+        _params = resolved.params;
         const raw = await this.fetcher.fetchRawOrderBook(outcomeId);
         return this.normalizer.normalizeOrderBook(raw, outcomeId);
     }