DOCSEARCHbyAlgolia
Submit Docs

PMXT Documentation

repository·main·Indexed 22 days ago

https://github.com/pmxt-dev/pmxt

A unified Python and TypeScript SDK for interacting with prediction markets such as Polymarket, Kalshi, and Limitless. PMXT supports hosted services via API keys and self-hosted local sidecar access. The ecosystem includes the pmxtjs Node.js SDK, a Python SDK, a global CLI (@pmxt/cli), and Model Context Protocol (MCP) support for AI agents. Key functionality includes fetching market data, managing accounts, executing trades with EIP-712 signing, and WebSocket streaming for order books and trades.

Tokens
157.1K
Snippets
348
Records
851
Agent score
84%

What's inside PMXT

  1. Explore API Reference example categories

    main

    The API reference examples are categorized into the following functional folders:

    • market-data/: Fetching markets, events, order books, trades, and OHLCV data.
    • trading/: Placing, cancelling, and querying orders.
    • account/: Balances and positions.
    • filtering/: Client-side filtering of markets and events.
    • pricing/: Execution price calculations from order book data.
    • streaming/: WebSocket streaming (order books, trades).
    • exchange-specific/: Methods unique to a single exchange.
    • errors/: Error handling patterns.

  2. Overview of adding a new exchange to pmxt

    main

    To add a new prediction market exchange, you must implement an exchange directory in core/src/exchanges/<name>/. An implementation typically consists of several files responsible for API specifications, utility mappings, error handling, authentication, data fetching (REST), and real-time streaming (WebSocket).

    | File | Purpose |
|------|---------|
| `api.ts` | Auto-generated from the exchange's OpenAPI spec -- the source of all implicit API methods |
| `utils.ts` | API URLs, status mapping, `mapMarketToUnified()` helper |
| `errors.ts` | Exchange-specific error patterns extending `ErrorMapper` |
| `auth.ts` | Credential validation, header/signer generation |
| `fetchMarkets.ts` | Fetch and normalize markets to `UnifiedMarket[]` |
| `fetchEvents.ts` | Fetch and normalize events to `UnifiedEvent[]` |
| `fetchOHLCV.ts` | Historical candle data mapped to `PriceCandle[]` |
| `fetchOrderBook.ts` | *(optional)* Order book -- create if the logic is complex enough to warrant it |
| `fetchTrades.ts` | *(optional)* Trade history -- create if the logic is complex enough to warrant it |
| `websocket.ts` | Real-time streaming (`watchOrderBook`, `watchTrades`, `close`) |
| `index.ts` | Main class: constructor calls `defineImplicitApi`, methods use `callApi` |

  3. What is the PMXT Router?

    main

    The Router is PMXT's cross-venue intelligence layer. It provides a unified view of hosted catalog venues through a single interface using a single API key. Instead of fanning out to individual venue APIs, the Router queries a continuously-updated Postgres catalog, allowing for high-performance (~10ms) cross-venue search, market matching, and price comparison.

    Key capabilities include:

    • Cross-venue search: Search markets and events across the hosted catalog in a single query.
    • Market matching: Find clusters of semantically equivalent markets across different venues (e.g., finding an 'identity' match even if titles differ).
    • Price comparison: Compare side-by-side bid/ask prices for matched markets to identify best execution.
    • Related markets: Find markets with resolution conditions that are subsets or supersets of a target market.

    Note: The Router is currently read-only. Smart order routing (best-execution) is planned for a future release.

  4. Understand Arbitrage and Matching results

    main

    The SDK includes specialized models for identifying opportunities:

    • ArbitrageOpportunity: Identifies price discrepancies between two markets (market_a and market_b) and provides the spread, buy_venue, and sell_venue.
    • MatchedMarketPair: Represents two markets that have been matched based on price differences and relationship.
    • MatchResult: Details how a specific market relates to a source market, including confidence and reasoning.

  6. How historical order book data works

    main

    Historical order book data is served from the PMXT Archive. This allows you to query tick-level data directly via the API (using since and until parameters) without having to manually download and parse Parquet files.

    Supported exchanges for historical fetchOrderBook include:

    • Polymarket
    • Kalshi
    • Limitless
    • Opinion

  7. How hosted vs self-hosted PMXT works

    main

    The SDK supports two operational modes:

    Hosted (Default/Recommended)

    When you provide a pmxtApiKey, the SDK communicates with PMXT's hosted services (api.pmxt.dev for catalogs and trade.pmxt.dev for trading). The SDK does not spawn a local process. For venues like Polymarket, Opinion, and Limitless, PMXT's PreFundedEscrow handles custody; you sign orders with your own key, and PMXT settles on-chain.

    Self-hosted (Advanced)

    If you omit pmxtApiKey, the SDK uses a local PMXT service (sidecar). You must install pmxt-core from npm and supply venue credentials directly (e.g., privateKey, apiKey). This mode is used for local venue integrations.

  8. Distinguish between Catalog UUID and Venue ID

    main

    When interacting with the PMXT API, you may encounter two types of identifiers:

    • Catalog UUID: A stable, unique identifier assigned by PMXT to every market and outcome. This is used for cross-venue identity, such as Router results and portfolio analytics.
    • Venue ID: The native identifier used by the underlying exchange (e.g., Polymarket, Kalshi). This might be a hex condition ID, a ticker, or a hash.

    The hosted trading API accepts both. If you pass a Venue ID, the SDK will automatically map it to the correct wire field.

  9. Understand the Prediction Market hierarchy

    main

    Prediction markets follow a three-tier hierarchy:

    1. Event: The broad topic (e.g., "Who will Trump nominate as Fed Chair?"
    2. Market: A specific tradeable question (e.g., "Will Trump nominate Kevin Warsh as the next Fed Chair?"
    3. Outcome: The actual share you buy (e.g., "Yes" or "No"")

  10. Understanding the Unified vs. Implicit API patterns

    main

    PMXT exchanges provide two layers of API access:

    1. Unified API: A standardized public interface defined in BaseExchange (e.g., fetchMarkets, createOrder). This allows you to write code that works across different exchanges using the same method names and data formats.
    2. Implicit API: Auto-generated methods derived directly from an exchange's specific OpenAPI specification. These allow you to call exchange-specific endpoints that aren't part of the unified interface.

    How they interact: Unified methods typically implement their logic by calling the Implicit API via the callApi() method. For example, a unified fetchOrderBook method might internally call this.callApi('GetMarketOrderbook', { ticker: id }) to reach the exchange's specific endpoint.

  11. Understand the difference between Hosted and Self-hosted modes

    main

    PMXT operates in two distinct modes with different security models and credential requirements. Choosing between them depends on your need for latency, custody control, and specific venue credential support.

    ModeWhat you provideWhat touches PMXT's serverCustody Model
    Hosted (Default)EIP-712 signatures (never your private key)Outcome target, signatures, public wallet addressUSDC in an on-chain PreFundedEscrow controlled via timelock
    Self-hostedRaw venue credentials (e.g., API keys, private keys)Nothing (PMXT cloud is not involved)Your venue account/wallet directly

    When to use each:

    • Use Hosted for most use cases. It is the default, non-custodial mode where your private key never leaves your local process.
    • Use Self-hosted if you require:
      • Raw venue credentials (e.g., Polymarket L2 API keys, Kalshi RSA).
      • Sub-100ms latency.
      • Specific regulatory custody constraints.

  12. Interpret outcome prices as probabilities

    main

    In PMXT, outcome prices are expressed as values in the closed interval [0, 1]. These prices represent the market's implied probability that the outcome will resolve true.

    • A price of 0.31 implies a ~31% chance of the outcome occurring.
    • For a binary market (Yes/No), the sum of the 'Yes' price and the 'No' price will approximately equal 1 (accounting for venue spread).