Modular 3-layer architecture (fetcher → normalizer → sdk)

[alexandretrotel]

I’d like to propose a small structural improvement to make exchange integrations more explicitly modular and plug-and-play.

By venue, I mean every prediction market supported like Polymarket, Kalshi, etc.

Idea

For each venue, it would be great to clearly separate:

1. Fetch layer
   Responsible for calling the venue API (via callApi), handling pagination/rate limits, and returning venue-native/raw data.

2. Normalization layer
   Responsible for mapping venue-native shapes into pmxt unified types (UnifiedMarket, etc.).

3. SDK class (composition layer)
   Finally, the SDK class wires fetchers + normalizers together and exposes the unified methods defined in BaseExchange.

The sidecar model and SDKs remain unchanged.

Why

Right now, fetching and normalization logic are often mixed inside exchange implementations or utilities. Making the boundary explicit would:

• Make venues easier to reason about
• Improve testability (mock fetchers separately from normalizers)
• Allow advanced users to reuse only part of the stack
  • e.g. reuse pmxt’s Polymarket fetch layer but plug in a custom normalizer
  • or reuse pmxt’s normalization but fetch from a custom data source
• Make adding new venues more straightforward

And, of course, we could have shared utilities if multiple venus share the same logic, but again, this should be explicit.

I won't have time for now to make a PR on this but I could help in the future. Anyone can take it until then.

[alexandretrotel]

Here's a small example to understand.

⚠️ Note: This is only a simplified demo to showcase the proposed structure. It is not tied to the current pmxt repo and does not reflect its actual implementation. Generated with ChatGPT for demonstration only.

// ----------------------------------
// Unified types (already exist in pmxt)
// ----------------------------------

export interface UnifiedMarket {
  id: string;
  question: string;
  outcomes: string[];
  venue: string;
}

// ----------------------------------
// 1. Fetch Layer (venue-native)
// ----------------------------------

export interface PolymarketRawMarket {
  conditionId: string;
  title: string;
  outcomes: { name: string }[];
}

export class PolymarketFetcher {
  constructor(private readonly callApi: (path: string) => Promise<any>) {}

  async fetchMarkets(): Promise<PolymarketRawMarket[]> {
    const data = await this.callApi("/markets");
    return data.markets as PolymarketRawMarket[];
  }
}

// ----------------------------------
// 2. Normalization Layer
// ----------------------------------

export class PolymarketNormalizer {
  toUnifiedMarket(raw: PolymarketRawMarket): UnifiedMarket {
    return {
      id: raw.conditionId,
      question: raw.title,
      outcomes: raw.outcomes.map(o => o.name),
      venue: "polymarket",
    };
  }

  toUnifiedMarkets(rawMarkets: PolymarketRawMarket[]): UnifiedMarket[] {
    return rawMarkets.map(m => this.toUnifiedMarket(m));
  }
}

// ----------------------------------
// 3. SDK / Composition Layer
// ----------------------------------

export abstract class BaseExchange {
  abstract getMarkets(): Promise<UnifiedMarket[]>;
}

export class PolymarketExchange extends BaseExchange {
  constructor(
    private readonly fetcher: PolymarketFetcher,
    private readonly normalizer: PolymarketNormalizer
  ) {
    super();
  }

  async getMarkets(): Promise<UnifiedMarket[]> {
    const rawMarkets = await this.fetcher.fetchMarkets();
    return this.normalizer.toUnifiedMarkets(rawMarkets);
  }
}

// ----------------------------------
// Example usage
// ----------------------------------

const callApi = async (path: string) => {
  // dummy implementation
  return {
    markets: [
      {
        conditionId: "123",
        title: "Will BTC be above $100k by 2027?",
        outcomes: [{ name: "Yes" }, { name: "No" }],
      },
    ],
  };
};

const exchange = new PolymarketExchange(
  new PolymarketFetcher(callApi),
  new PolymarketNormalizer()
);

exchange.getMarkets().then(console.log);

What This Enables

Because everything is explicitly separated, advanced usage becomes trivial:

// Reuse fetch layer, custom normalization
const customExchange = new PolymarketExchange(
  new PolymarketFetcher(callApi),
  new MyCustomNormalizer()
);

// Or reuse normalization with custom data source
const rawMarkets = await myDatabase.getPolymarketMarkets();
const normalized = new PolymarketNormalizer().toUnifiedMarkets(rawMarkets);

This keeps the architecture clean, composable, and easier to extend as more venues are added.

[realfishsam]

Closed in 2.20.2