poly-sdk Documentation

The @catalyst-team/poly-sdk is a comprehensive TypeScript SDK for Polymarket. It provides a unified interface for trading, accessing market data, analyzing 'smart money' movements, performing on-chain operations, and detecting arbitrage opportunities.

Key features include:

• Unified API: Single access point for all Polymarket functionalities.
• Type Safety: Full TypeScript support and definitions.
• Rate Limiting: Built-in rate limiting per API endpoint.
• Caching: TTL-based caching with pluggable adapters.
• Error Handling: Structured error codes and automatic retries.
• WebSocket Support: Real-time price and order book updates via RealtimeServiceV2.

The documentation is organized into several functional areas to help you navigate from learning to contributing:

• Concepts: Deep dives into Polymarket principles and mental models.
• API Reference: Detailed documentation of the available SDK methods and interfaces.
• Practical Guides: Implementation recipes for tasks like copy trading and arbitrage.
• Architecture: Internal details regarding service layers, WebSockets, and data models for contributors.
• Arbitrage: Specialized documentation for arbitrage mechanics and testing.

The PolymarketSDK provides access to several specialized clients for different parts of the Polymarket ecosystem:

• PolymarketSDK: The main entry point.
• ClobApiClient: For interacting with the Central Limit Order Book (CLOB).
• GammaApiClient: For accessing Gamma-related market data.
• DataApiClient: For general data retrieval.
• TradingClient: For executing trades.
• BridgeClient: For bridge-related operations.
• CTFClient: For Conditional Token Framework operations.
• WebSocketManager: For managing real-time WebSocket connections.

Each CTFManager instance is bound to a single market (one conditionId and its associated tokens). To monitor multiple markets simultaneously, instantiate a separate CTFManager for each market and start them all.

const markets = [
  { conditionId: '0x...', primary: '123...', secondary: '456...' },
  { conditionId: '0x...', primary: '789...', secondary: 'abc...' },
];

const managers = markets.map(market => new CTFManager({
  privateKey: '0x...',
  conditionId: market.conditionId,
  primaryTokenId: market.primary,
  secondaryTokenId: market.secondary,
}));

await Promise.all(managers.map(m => m.start()));

A high-capital strategy where the trader provides liquidity by holding equal amounts of 'Yes' and 'No' positions in the same market. The goal is not to predict the outcome, but to profit from the bid-ask spread.

Core Mechanics:

• Dual-Sided Positions: Holding equal amounts of 'Yes' and 'No' (e.g., $701,000 in 'Yes' and $701,000 in 'No').
• Spread Capture: Profiting from the difference between the buy and sell price (e.g., buying at 0.49 and selling at 0.51).
• Extreme Diversification: Spreading capital across a vast number of markets (e.g., 99+ positions) and diverse sectors (NBA, NFL, NHL, Soccer, Politics, Esports).

Requirements/Warnings:

• Requires significant capital (e.g., $1.4M+).
• Requires rapid execution capabilities.
• Not recommended for retail players due to the focus on spread mechanics rather than outcome prediction.

The SDK supports Conditional Token Framework (CTF) operations for managing liquidity in arbitrage:

• Split: Converts USDC into paired YES and NO tokens for a specific market condition.
• Merge: Converts paired YES and NO tokens back into USDC.

Operational Notes:

• Gas Costs: On Polygon, Split and Merge operations are highly efficient, typically costing ~100k gas (~$0.03 USD).
• Slippage: Testing shows successful round-trips ($5 → tokens → $5) with zero slippage in controlled environments.

The CTF is based on the Gnosis Conditional Tokens framework. It allows for the creation of outcome-based tokens where the sum of all possible outcomes equals the collateral amount (e.g., 1 USDC).

Core Constraint

YES + NO = 1 USDC (before market settlement).

Token Operations

Key Implications

• If the price of a YES token is 0.65, the NO token price must be approximately 0.35.
• Arbitrage opportunities exist when YES + NO ≠ 1.

The poly-sdk uses a 7-state internal OrderStatus enum to track orders from creation to settlement. These states are categorized into Active States (can transition to other states) and Terminal States (final states).

Active States

• pending: Order created locally, not yet submitted.
• open: Order is in the orderbook, awaiting fills.
• partially_filled: Order has been partially filled; the remainder is still in the orderbook.

Terminal States

• filled: Order is completely filled.
• cancelled: Order was cancelled by the user or the system.
• expired: A GTD (Good-Til-Date) order reached its expiration time.
• rejected: Order failed validation before it could be submitted.