feat: add unified semantic shortcuts (.yes/.no) for binary markets across all SDKs

realfishsam · realfishsam · commit f564205cef21 · 2026-01-29T12:47:24.000+02:00
diff --git a/changelog.md b/changelog.md
@@ -2,6 +2,18 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.2.0] - 2026-01-29
+
+### Added
+- **Unified Semantic Shortcuts**: Introduced convenience properties for binary markets across all SDKs (Python and TypeScript).
+  - **New Properties**: `market.yes`, `market.no`, `market.up`, and `market.down`.
+  - **Intelligent Mapping**: Implemented shared core logic to automatically identify "Yes" vs "No" outcomes based on labels and common patterns (e.g., "Not X" pairs).
+  - **Expressive Aliases**: Added `.up` and `.down` as semantic aliases for `.yes` and `.no` to improve readability for directional markets.
+
+### Improved
+- **Core Architecture**: Extracted market normalization logic into a shared utility to ensure absolute parity between exchange implementations.
+- **SDK Parity**: Updated both auto-generated and handcrafted portions of the Python and TypeScript SDKs to expose the new fields with full type hinting.
+
 ## [1.1.4] - 2026-01-27
 
 ### Fixed
diff --git a/core/package.json b/core/package.json
@@ -1,6 +1,6 @@
 {
   "name": "pmxt-core",
-  "version": "1.0.0-b4",
+  "version": "1.2.0",
   "description": "pmxt is a unified prediction market data API. The ccxt for prediction markets.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
diff --git a/core/src/exchanges/kalshi/utils.ts b/core/src/exchanges/kalshi/utils.ts
@@ -1,4 +1,5 @@
 import { UnifiedMarket, MarketOutcome, CandleInterval } from '../../types';
+import { addBinaryOutcomes } from '../../utils/market-utils';
 
 export const KALSHI_API_URL = "https://api.elections.kalshi.com/trade-api/v2/events";
 export const KALSHI_SERIES_URL = "https://api.elections.kalshi.com/trade-api/v2/series";
@@ -60,7 +61,7 @@ export function mapMarketToUnified(event: any, market: any): UnifiedMarket | nul
         }
     }
 
-    return {
+    const um = {
         id: market.ticker,
         title: event.title,
         description: market.rules_primary || market.rules_secondary || "",
@@ -73,7 +74,10 @@ export function mapMarketToUnified(event: any, market: any): UnifiedMarket | nul
         url: `https://kalshi.com/events/${event.event_ticker}`,
         category: event.category,
         tags: unifiedTags
-    };
+    } as UnifiedMarket;
+
+    addBinaryOutcomes(um);
+    return um;
 }
 
 export function mapIntervalToKalshi(interval: CandleInterval): number {
diff --git a/core/src/exchanges/polymarket/utils.ts b/core/src/exchanges/polymarket/utils.ts
@@ -1,4 +1,5 @@
 import { UnifiedMarket, MarketOutcome, CandleInterval } from '../../types';
+import { addBinaryOutcomes } from '../../utils/market-utils';
 
 export const GAMMA_API_URL = 'https://gamma-api.polymarket.com/events';
 export const CLOB_API_URL = 'https://clob.polymarket.com';
@@ -69,7 +70,7 @@ export function mapMarketToUnified(event: any, market: any, options: { useQuesti
         });
     }
 
-    return {
+    const um = {
         id: market.id,
         title: market.question ? `${event.title} - ${market.question}` : event.title,
         description: market.description || event.description,
@@ -83,7 +84,10 @@ export function mapMarketToUnified(event: any, market: any, options: { useQuesti
         image: event.image || market.image || `https://polymarket.com/api/og?slug=${event.slug}`,
         category: event.category || event.tags?.[0]?.label,
         tags: event.tags?.map((t: any) => t.label) || []
-    };
+    } as UnifiedMarket;
+
+    addBinaryOutcomes(um);
+    return um;
 }
 
 export function mapIntervalToFidelity(interval: CandleInterval): number {
diff --git a/core/src/server/openapi.yaml b/core/src/server/openapi.yaml
@@ -647,6 +647,14 @@ components:
           type: array
           items:
             type: string
+        "yes":
+          $ref: '#/components/schemas/MarketOutcome'
+        "no":
+          $ref: '#/components/schemas/MarketOutcome'
+        up:
+          $ref: '#/components/schemas/MarketOutcome'
+        down:
+          $ref: '#/components/schemas/MarketOutcome'
 
     MarketOutcome:
       type: object
diff --git a/core/src/types.ts b/core/src/types.ts
@@ -30,6 +30,12 @@ export interface UnifiedMarket {
 
     category?: string;
     tags?: string[];
+
+    // Convenience getters for binary markets
+    yes?: MarketOutcome;
+    no?: MarketOutcome;
+    up?: MarketOutcome;
+    down?: MarketOutcome;
 }
 
 export type CandleInterval = '1m' | '5m' | '15m' | '1h' | '6h' | '1d';
diff --git a/core/src/utils/market-utils.ts b/core/src/utils/market-utils.ts
@@ -0,0 +1,42 @@
+import { MarketOutcome, UnifiedMarket } from '../types';
+
+/**
+ * Standardizes binary market outcomes into yes/no/up/down properties.
+ */
+export function addBinaryOutcomes(market: UnifiedMarket): void {
+    const outcomes = market.outcomes;
+    if (outcomes.length !== 2) return;
+
+    const o1 = outcomes[0];
+    const o2 = outcomes[1];
+    const l1 = o1.label.toLowerCase();
+    const l2 = o2.label.toLowerCase();
+
+    // 1. Check for explicit opposites
+    const isYes = (l: string) => l === 'yes' || l === 'up' || l === 'over';
+    const isNo = (l: string) => l === 'no' || l === 'down' || l === 'under';
+
+    if (isYes(l1) || isNo(l2)) {
+        market.yes = o1;
+        market.no = o2;
+    } else if (isYes(l2) || isNo(l1)) {
+        market.yes = o2;
+        market.no = o1;
+    }
+    // 2. Check for "Not" pattern
+    else if (l2.startsWith('not ')) {
+        market.yes = o1;
+        market.no = o2;
+    } else if (l1.startsWith('not ')) {
+        market.yes = o2;
+        market.no = o1;
+    }
+    // 3. Fallback to indexing
+    else {
+        market.yes = o1;
+        market.no = o2;
+    }
+
+    market.up = market.yes;
+    market.down = market.no;
+}
diff --git a/core/test/utils/market-utils.test.ts b/core/test/utils/market-utils.test.ts
@@ -0,0 +1,90 @@
+import { addBinaryOutcomes } from '../../src/utils/market-utils';
+import { UnifiedMarket, MarketOutcome } from '../../src/types';
+
+describe('addBinaryOutcomes', () => {
+    const createMockMarket = (outcomeLabels: string[]): UnifiedMarket => {
+        const outcomes: MarketOutcome[] = outcomeLabels.map((label, index) => ({
+            id: `id-${index}`,
+            label,
+            price: 0.5
+        }));
+
+        return {
+            id: 'market-1',
+            title: 'Test Market',
+            description: 'Test Description',
+            outcomes,
+            resolutionDate: new Date(),
+            volume24h: 1000,
+            liquidity: 5000,
+            url: 'https://example.com'
+        } as UnifiedMarket;
+    };
+
+    test('should map explicit Yes/No outcomes', () => {
+        const market = createMockMarket(['Yes', 'No']);
+        addBinaryOutcomes(market);
+
+        expect(market.yes?.label).toBe('Yes');
+        expect(market.no?.label).toBe('No');
+    });
+
+    test('should map explicit Up/Down outcomes', () => {
+        const market = createMockMarket(['Up', 'Down']);
+        addBinaryOutcomes(market);
+
+        expect(market.up?.label).toBe('Up');
+        expect(market.down?.label).toBe('Down');
+        expect(market.yes?.label).toBe('Up');
+        expect(market.no?.label).toBe('Down');
+    });
+
+    test('should map "Not" patterns correctly', () => {
+        const market = createMockMarket(['Kevin Warsh', 'Not Kevin Warsh']);
+        addBinaryOutcomes(market);
+
+        expect(market.yes?.label).toBe('Kevin Warsh');
+        expect(market.no?.label).toBe('Not Kevin Warsh');
+    });
+
+    test('should handle reversed order correctly', () => {
+        const market = createMockMarket(['No', 'Yes']);
+        addBinaryOutcomes(market);
+
+        expect(market.yes?.label).toBe('Yes');
+        expect(market.no?.label).toBe('No');
+    });
+
+    test('should handle reversed "Not" order correctly', () => {
+        const market = createMockMarket(['Not Trump', 'Trump']);
+        addBinaryOutcomes(market);
+
+        expect(market.yes?.label).toBe('Trump');
+        expect(market.no?.label).toBe('Not Trump');
+    });
+
+    test('should map Over/Under correctly', () => {
+        const market = createMockMarket(['Over 2.5', 'Under 2.5']);
+        addBinaryOutcomes(market);
+
+        expect(market.yes?.label).toBe('Over 2.5');
+        expect(market.no?.label).toBe('Under 2.5');
+    });
+
+    test('should do nothing for non-binary markets', () => {
+        const market = createMockMarket(['Home', 'Away', 'Draw']);
+        addBinaryOutcomes(market);
+
+        expect(market.yes).toBeUndefined();
+        expect(market.no).toBeUndefined();
+    });
+
+    test('should fallback to first index if "Not" cannot be determined', () => {
+        // Obscure labels that don't match any patterns
+        const market = createMockMarket(['Alpha', 'Beta']);
+        addBinaryOutcomes(market);
+
+        expect(market.yes?.label).toBe('Alpha');
+        expect(market.no?.label).toBe('Beta');
+    });
+});
diff --git a/readme.md b/readme.md
@@ -73,9 +73,10 @@ import pmxt
 api = pmxt.Polymarket()
 markets = api.get_markets_by_slug('who-will-trump-nominate-as-fed-chair')
 
-warsh = next((m for m in markets if m.outcomes[0].label == 'Kevin Warsh'), None) 
+# Find the specific candidate in the election event
+warsh = next((m for m in markets if m.yes.label == 'Kevin Warsh'), None) 
 
-print(warsh.outcomes[0].price) # price of 'Yes' outcome
+print(f"Price: {warsh.yes.price}")
 ```
 
 > **Note**: For TypeScript usage, see [pmxtjs documentation](https://pmxt.dev/docs).
diff --git a/sdks/python/API_REFERENCE.md b/sdks/python/API_REFERENCE.md
@@ -535,8 +535,19 @@ url: str #
 image: str # 
 category: str # 
 tags: List[string] # 
+yes: MarketOutcome # Convenience access to Yes outcome
+no: MarketOutcome # Convenience access to No outcome
+up: MarketOutcome # Alias for .yes (used for Up/Down markets)
+down: MarketOutcome # Alias for .no (used for Up/Down markets)
 ```
 
+**Binary Outcome Mapping Logic:**
+
+PMXT automatically identifies binary outcomes for markets with exactly two outcomes using the following priority:
+1. **Explicit Labels**: Matches "Yes", "Up", or "Over".
+2. **Opposite Pattern**: Matches pairs like "Kevin Warsh" and "Not Kevin Warsh", identifying the non-"Not" side as `yes`.
+3. **Fallback**: If no pattern is matched, index 0 is mapped to `yes/up` and index 1 to `no/down`.
+
 ---
 ### `MarketOutcome`
 
diff --git a/sdks/python/pmxt/client.py b/sdks/python/pmxt/client.py
@@ -38,18 +38,20 @@
 from .server_manager import ServerManager
 
 
+def _convert_outcome(raw: Dict[str, Any]) -> MarketOutcome:
+    """Convert raw API response to MarketOutcome."""
+    return MarketOutcome(
+        id=raw.get("id"),
+        label=raw.get("label"),
+        price=raw.get("price"),
+        price_change_24h=raw.get("priceChange24h"),
+        metadata=raw.get("metadata"),
+    )
+
+
 def _convert_market(raw: Dict[str, Any]) -> UnifiedMarket:
     """Convert raw API response to UnifiedMarket."""
-    outcomes = [
-        MarketOutcome(
-            id=o.get("id"),
-            label=o.get("label"),
-            price=o.get("price"),
-            price_change_24h=o.get("priceChange24h"),
-            metadata=o.get("metadata"),
-        )
-        for o in raw.get("outcomes", [])
-    ]
+    outcomes = [_convert_outcome(o) for o in raw.get("outcomes", [])]
     
     return UnifiedMarket(
         id=raw.get("id"),
@@ -65,6 +67,10 @@ def _convert_market(raw: Dict[str, Any]) -> UnifiedMarket:
         image=raw.get("image"),
         category=raw.get("category"),
         tags=raw.get("tags"),
+        yes=_convert_outcome(raw["yes"]) if raw.get("yes") else None,
+        no=_convert_outcome(raw["no"]) if raw.get("no") else None,
+        up=_convert_outcome(raw["up"]) if raw.get("up") else None,
+        down=_convert_outcome(raw["down"]) if raw.get("down") else None,
     )
 
 
diff --git a/sdks/python/pmxt/models.py b/sdks/python/pmxt/models.py
@@ -75,6 +75,18 @@ class UnifiedMarket:
     tags: Optional[List[str]] = None
     """Market tags"""
 
+    yes: Optional[MarketOutcome] = None
+    """Convenience access to the Yes outcome for binary markets."""
+
+    no: Optional[MarketOutcome] = None
+    """Convenience access to the No outcome for binary markets."""
+
+    up: Optional[MarketOutcome] = None
+    """Convenience access to the Up outcome for binary markets."""
+
+    down: Optional[MarketOutcome] = None
+    """Convenience access to the Down outcome for binary markets."""
+
 
 @dataclass
 class PriceCandle:
diff --git a/sdks/python/pyproject.toml b/sdks/python/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pmxt"
-version = "1.0.0b4"
+version = "1.2.0"
 description = "Unified prediction market data API - The ccxt for prediction markets"
 readme = "README.md"
 requires-python = ">=3.8"
diff --git a/sdks/typescript/API_REFERENCE.md b/sdks/typescript/API_REFERENCE.md
@@ -535,9 +535,20 @@ interface UnifiedMarket {
   image: string; // 
   category: string; // 
   tags: string[]; // 
+  yes: MarketOutcome; // Convenience access to Yes outcome
+  no: MarketOutcome; // Convenience access to No outcome
+  up: MarketOutcome; // Alias for .yes (used for Up/Down markets)
+  down: MarketOutcome; // Alias for .no (used for Up/Down markets)
 }
 ```
 
+**Binary Outcome Mapping Logic:**
+
+PMXT automatically identifies binary outcomes for markets with exactly two outcomes using the following priority:
+1. **Explicit Labels**: Matches "Yes", "Up", or "Over".
+2. **Opposite Pattern**: Matches pairs like "Kevin Warsh" and "Not Kevin Warsh", identifying the non-"Not" side as `yes`.
+3. **Fallback**: If no pattern is matched, index 0 is mapped to `yes/up` and index 1 to `no/down`.
+
 ---
 ### `MarketOutcome`
 
diff --git a/sdks/typescript/generated/docs/UnifiedMarket.md b/sdks/typescript/generated/docs/UnifiedMarket.md
@@ -19,6 +19,10 @@ Name | Type
 `image` | string
 `category` | string
 `tags` | Array&lt;string&gt;
+`yes` | [MarketOutcome](MarketOutcome.md)
+`no` | [MarketOutcome](MarketOutcome.md)
+`up` | [MarketOutcome](MarketOutcome.md)
+`down` | [MarketOutcome](MarketOutcome.md)
 
 ## Example
 
@@ -40,6 +44,10 @@ const example = {
   "image": null,
   "category": null,
   "tags": null,
+  "yes": null,
+  "no": null,
+  "up": null,
+  "down": null,
 } satisfies UnifiedMarket
 
 console.log(example)
diff --git a/sdks/typescript/generated/src/models/UnifiedMarket.ts b/sdks/typescript/generated/src/models/UnifiedMarket.ts
diff --git a/sdks/typescript/package.json b/sdks/typescript/package.json
diff --git a/sdks/typescript/pmxt/client.ts b/sdks/typescript/pmxt/client.ts
diff --git a/sdks/typescript/pmxt/models.ts b/sdks/typescript/pmxt/models.ts

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "pmxt-core",`
`3`		`- "version": "1.0.0-b4",`
	`3`	`+ "version": "1.2.0",`
`4`	`4`	`"description": "pmxt is a unified prediction market data API. The ccxt for prediction markets.",`
`5`	`5`	`"main": "dist/index.js",`
`6`	`6`	`"types": "dist/index.d.ts",`