feat: consolidate API into unified fetchMarkets and fetchEvents (v1.7.0)

- Add fetchMarkets() with query/slug parameters (replaces searchMarkets/getMarketsBySlug)
- Add fetchEvents() with query parameter (replaces searchEvents)
- Deprecate old methods with console warnings (removal in v2.0)
- Update all examples and tests to use new API
- Update API references, changelog, and migration guide

Author: realfishsam

MIGRATION.md

@@ -1,6 +1,55 @@
 # Migration Guide
 
-## Feb 3, 2026 - v1.5.8: Unified Filtering
+## Feb 3, 2026 - v1.7.0: CCXT-Style Unified API
+
+### Change
+Consolidated `searchMarkets()`, `getMarketsBySlug()`, and `searchEvents()` into unified `fetchMarkets()` and `fetchEvents()` methods that accept optional parameters, following CCXT conventions.
+
+### What's Deprecated
+The following methods are now deprecated and will be removed in v2.0:
+- `searchMarkets(query, params)` → Use `fetchMarkets({ query, ...params })`
+- `getMarketsBySlug(slug)` → Use `fetchMarkets({ slug })`
+- `searchEvents(query, params)` → Use `fetchEvents({ query, ...params })`
+
+Deprecation warnings will appear in the console when using the old methods.
+
+### How to Migrate
+
+**TypeScript:**
+```typescript
+// OLD (deprecated)
+const markets = await exchange.searchMarkets('Trump', { limit: 10 });
+const bySlug = await exchange.getMarketsBySlug('fed-chair-2025');
+const events = await exchange.searchEvents('Election', { limit: 5 });
+
+// NEW (CCXT-style)
+const markets = await exchange.fetchMarkets({ query: 'Trump', limit: 10 });
+const bySlug = await exchange.fetchMarkets({ slug: 'fed-chair-2025' });
+const events = await exchange.fetchEvents({ query: 'Election', limit: 5 });
+```
+
+**Python:**
+```python
+# OLD (deprecated)
+markets = await exchange.search_markets('Trump', limit=10)
+by_slug = await exchange.get_markets_by_slug('fed-chair-2025')
+events = await exchange.search_events('Election', limit=5)
+
+# NEW (CCXT-style)
+markets = await exchange.fetch_markets(query='Trump', limit=10)
+by_slug = await exchange.fetch_markets(slug='fed-chair-2025')
+events = await exchange.fetch_events(query='Election', limit=5)
+```
+
+### Benefits
+- **Unified interface**: Single method for all market fetching operations
+- **CCXT compatibility**: Familiar API for CCXT users
+- **Cleaner code**: No need to remember different method names for different operations
+- **Backward compatible**: Old methods still work (with warnings) until v2.0
+
+---
+
+## Feb 3, 2026 - v1.6.0: Unified Filtering
 
 ### Change
 Introduced dedicated `filter_markets()` and `filter_events()` methods to replace manual list filtering and unify searching.

changelog.md

@@ -2,6 +2,25 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.7.0] - 2026-02-03
+
+### Added
+- **Unified API Consolidation**: Consolidated `searchMarkets()`, `getMarketsBySlug()`, and `searchEvents()` into new CCXT-style `fetchMarkets()` and `fetchEvents()` methods.
+  - New methods accept a unified `params` object (TS) or keyword arguments (Python).
+  - Supports `query` and `slug` as standard parameters.
+- **Improved CCXT Compatibility**: Aligned the API structure more closely with the CCXT standard for easier cross-platform migration.
+
+### Deprecated
+- `searchMarkets(query, params)`: Use `fetchMarkets({ query, ...params })` instead.
+- `getMarketsBySlug(slug)`: Use `fetchMarkets({ slug })` instead.
+- `searchEvents(query, params)`: Use `fetchEvents({ query, ...params })` instead.
+- These methods will be removed in v2.0. Deprecation warnings have been added.
+
+### Improved
+- **BaseExchange Architecture**: Moved search routing logic into the `BaseExchange` class to reduce duplication across exchange implementations.
+- **Example Modernization**: All core and SDK examples updated to use the new unified API patterns.
+- **Test Coverage**: Added compliance tests for the new `fetchMarkets` and `fetchEvents` implementations.
+
 ## [1.6.0] - 2026-02-03
 
 ### Added

core/API_REFERENCE.md

@@ -40,43 +40,53 @@ const poly = new pmxt.default.Polymarket();
 ## Core Methods
 
 ### `fetchMarkets(params?)`
-Get active markets from an exchange.
+Get active markets from an exchange. This is the unified method for all market fetching operations.
+
+**Parameters**:
+- `limit`: Number of results (default: 20)
+- `offset`: Pagination offset
+- `sort`: 'volume' | 'liquidity' | 'newest'
+- `query`: Search text (replaces `searchMarkets`)
+- `slug`: Market slug or ticker (replaces `getMarketsBySlug`)
 
 ```typescript
+// 1. Fetch recent markets
 const markets = await polymarket.fetchMarkets({ 
   limit: 20, 
-  offset: 0,
-  sort: 'volume' // 'volume' | 'liquidity' | 'newest'
+  sort: 'volume' 
 });
-```
 
-### `searchMarkets(query, params?)`
-Search markets by keyword. By default, searches only in titles.
+// 2. Search by text (replaces searchMarkets)
+const results = await kalshi.fetchMarkets({ 
+  query: 'Fed rates',
+  limit: 10
+});
 
-```typescript
-const results = await kalshi.searchMarkets('Fed rates', { 
-  limit: 10,
-  searchIn: 'title' // 'title' (default) | 'description' | 'both'
+// 3. Fetch by slug/ticker (replaces getMarketsBySlug)
+const market = await polymarket.fetchMarkets({ 
+  slug: 'who-will-trump-nominate-as-fed-chair'
 });
 ```
 
-### `getMarketsBySlug(slug)`
-Fetch markets by URL slug/ticker.
+### `fetchEvents(params?)`
+Get events (groups of related markets). Unified method for event fetching.
 
-```typescript
-// Polymarket: use URL slug
-const polyMarkets = await polymarket.getMarketsBySlug('who-will-trump-nominate-as-fed-chair');
+**Parameters**:
+- `query`: Search text
+- `limit`: Number of results
+- `offset`: Pagination offset
 
-// Kalshi: use market ticker (auto-uppercased)
-const kalshiMarkets = await kalshi.getMarketsBySlug('KXFEDCHAIRNOM-29');
+```typescript
+// Search for events
+const events = await polymarket.fetchEvents({ 
+  query: 'Fed Chair',
+  limit: 5 
+});
 ```
 
-#### Universal Slug/Ticker Reference
+---
+
 
-| Platform | Example Market URL | What to extract (Slug/Ticker) | Logic |
-|---|---|---|---|
-| **Kalshi** | `kalshi.com/markets/kxfedchairnom/.../kxfedchairnom-29` | `KXFEDCHAIRNOM-29` | The **last** path segment of the URL. |
-| **Polymarket** | `polymarket.com/event/who-will-trump-nominate-as-fed-chair` | `who-will-trump-nominate-as-fed-chair` | The slug immediately after `/event/`. |
 
 ---
 
@@ -90,7 +100,7 @@ Get historical price candles.
 - **Kalshi**: `outcome.outcomeId` is the Market Ticker
 
 ```typescript
-const markets = await polymarket.searchMarkets('Trump');
+const markets = await polymarket.fetchMarkets({ query: 'Trump' });
 const outcomeId = markets[0].outcomes[0].outcomeId; // Get the outcome ID
 
 const candles = await polymarket.fetchOHLCV(outcomeId, {
@@ -228,7 +238,7 @@ interface ExecutionPriceResult {
 
 ```typescript
 // 1. Search for markets
-const markets = await polymarket.searchMarkets('Fed Chair');
+const markets = await polymarket.fetchMarkets({ query: 'Fed Chair' });
 const market = markets[0];
 
 // 2. Get outcome details
@@ -493,7 +503,7 @@ const [balance] = await exchange.fetchBalance();
 console.log(`Available: $${balance.available}`);
 
 // 2. Search for a market
-const markets = await exchange.searchMarkets('Trump');
+const markets = await exchange.fetchMarkets({ query: 'Trump' });
 const market = markets[0];
 const outcome = market.outcomes[0];
 

core/examples/filtering-example.ts

@@ -16,15 +16,15 @@ async function main() {
     // Example 1: Simple text search
     // ----------------------------------------------------------------------------
     console.log('Example 1: Simple text search');
-    const allMarkets = await api.searchMarkets('Trump');
+    const allMarkets = await api.fetchMarkets({ query: 'Trump' });
     const filtered1 = api.filterMarkets(allMarkets, 'Fed Chair');
     console.log(`Found ${filtered1.length} markets matching "Fed Chair"\n`);
 
     // ----------------------------------------------------------------------------
     // Example 2: Multi-field text search
     // ----------------------------------------------------------------------------
     console.log('Example 2: Multi-field text search');
-    const events = await api.searchEvents('Election');
+    const events = await api.fetchEvents({ query: 'Election' });
     const filtered2 = api.filterMarkets(events[0]?.markets || [], {
         text: 'Trump',
         searchIn: ['title', 'description', 'tags']
@@ -112,7 +112,7 @@ async function main() {
     // Example 9: Event filtering
     // ----------------------------------------------------------------------------
     console.log('Example 9: Event filtering');
-    const allEvents = await api.searchEvents('2024');
+    const allEvents = await api.fetchEvents({ query: '2024' });
     const filtered9 = api.filterEvents(allEvents, {
         text: 'Trump',
         category: 'Politics',
@@ -125,7 +125,7 @@ async function main() {
     // Example 10: Combining global search with filtering
     // ----------------------------------------------------------------------------
     console.log('Example 10: Global search + filtering');
-    const markets = await api.searchMarkets('Election');
+    const markets = await api.fetchMarkets({ query: 'Election' });
     const undervalued = api.filterMarkets(markets, {
         price: { outcome: 'yes', max: 0.3 },
         volume24h: { min: 5000 },

core/examples/market-data/get_event_prices.ts

@@ -2,7 +2,7 @@ import pmxt from '../../src';
 
 const main = async () => {
     const api = new pmxt.Polymarket();
-    const markets = await api.getMarketsBySlug('who-will-trump-nominate-as-fed-chair');
+    const markets = await api.fetchMarkets({ slug: 'who-will-trump-nominate-as-fed-chair' });
     const warsh = markets.find(m => m.outcomes[0]?.label === 'Kevin Warsh');
 
     console.log(warsh?.outcomes[0].price);

core/examples/market-data/historical_prices.ts

@@ -2,7 +2,7 @@ import pmxt from '../../src';
 
 const main = async () => {
     const api = new pmxt.Polymarket();
-    const markets = await api.getMarketsBySlug('who-will-trump-nominate-as-fed-chair');
+    const markets = await api.fetchMarkets({ slug: 'who-will-trump-nominate-as-fed-chair' });
     const warsh = markets.find(m => m.outcomes[0]?.label === 'Kevin Warsh');
 
     const history = await api.fetchOHLCV(warsh!.outcomes[0].metadata.clobTokenId, {

core/examples/market-data/orderbook.ts

@@ -2,7 +2,7 @@ import pmxt from '../../src';
 
 const main = async () => {
     const api = new pmxt.Kalshi();
-    const markets = await api.getMarketsBySlug('KXFEDCHAIRNOM-29');
+    const markets = await api.fetchMarkets({ slug: 'KXFEDCHAIRNOM-29' });
     const warsh = markets.find(m => m.outcomes[0]?.label === 'Kevin Warsh');
 
     const book = await api.fetchOrderBook(warsh!.id);

core/examples/market-data/recent_trades.ts

@@ -3,14 +3,14 @@ import pmxt from '../../src';
 const main = async () => {
     // Kalshi
     const kalshi = new pmxt.Kalshi();
-    const kMarkets = await kalshi.getMarketsBySlug('KXFEDCHAIRNOM-29');
+    const kMarkets = await kalshi.fetchMarkets({ slug: 'KXFEDCHAIRNOM-29' });
     const kWarsh = kMarkets.find(m => m.outcomes[0]?.label === 'Kevin Warsh');
     const kTrades = await kalshi.fetchTrades(kWarsh!.id, { limit: 10 });
     console.log('Kalshi:', kTrades);
 
     // Polymarket
     const poly = new pmxt.Polymarket();
-    const pMarkets = await poly.getMarketsBySlug('who-will-trump-nominate-as-fed-chair');
+    const pMarkets = await poly.fetchMarkets({ slug: 'who-will-trump-nominate-as-fed-chair' });
     const pWarsh = pMarkets.find(m => m.outcomes[0]?.label === 'Kevin Warsh');
     const pTrades = await poly.fetchTrades(pWarsh!.outcomes[0].metadata.clobTokenId, { limit: 10 });
     console.log('Polymarket:', pTrades);

core/examples/market-data/search_events.ts

@@ -4,7 +4,7 @@ const main = async () => {
     const poly = new pmxt.Polymarket();
     // const kalshi = new pmxt.Kalshi();
 
-    const events = await poly.searchEvents('Fed Chair');
+    const events = await poly.fetchEvents({ query: 'Fed Chair' });
 
     events.forEach(event => {
         console.log(`Event: ${event.title}`);

core/examples/market-data/search_markets.ts

@@ -4,8 +4,8 @@ const main = async () => {
     const poly = new pmxt.Polymarket();
     const kalshi = new pmxt.Kalshi();
 
-    console.log('Polymarket:', await poly.searchMarkets('Fed'));
-    console.log('Kalshi:', await kalshi.searchMarkets('Fed'));
+    console.log('Polymarket:', await poly.fetchMarkets({ query: 'Fed' }));
+    console.log('Kalshi:', await kalshi.fetchMarkets({ query: 'Fed' }));
 };
 
 main();