@catalyst-team/poly-sdk 0.1.0

package/dist/clients/gamma-api.js

@@ -0,0 +1,352 @@
+/**
+ * Gamma API Client for Polymarket
+ *
+ * The Gamma API provides rich market discovery and metadata. Unlike the CLOB API
+ * which is focused on trading, Gamma is optimized for browsing, searching, and
+ * discovering prediction markets.
+ *
+ * @remarks
+ * - Base URL: https://gamma-api.polymarket.com
+ * - Best for: Market discovery, trending markets, event groupings
+ * - Rate limits are automatically handled by the RateLimiter
+ *
+ * @example
+ * ```typescript
+ * import { GammaApiClient, RateLimiter, Cache } from '@prediction-router/poly-sdk';
+ *
+ * const client = new GammaApiClient(new RateLimiter(), new Cache());
+ *
+ * // Get trending markets by 24h volume
+ * const trending = await client.getTrendingMarkets(20);
+ *
+ * // Search for specific markets
+ * const btcMarkets = await client.getMarkets({
+ *   active: true,
+ *   closed: false,
+ *   order: 'volume24hr',
+ *   ascending: false,
+ *   limit: 10,
+ * });
+ * ```
+ *
+ * @see {@link https://docs.polymarket.com/#gamma-api Gamma API Documentation}
+ *
+ * @module clients/gamma-api
+ */
+import { ApiType } from '../core/rate-limiter.js';
+import { PolymarketError } from '../core/errors.js';
+/** Gamma API base URL */
+const GAMMA_API_BASE = 'https://gamma-api.polymarket.com';
+// ===== Client =====
+/**
+ * Gamma API client for market discovery and metadata
+ *
+ * @remarks
+ * Use this client for:
+ * - Discovering trending markets
+ * - Searching for specific topics
+ * - Getting market metadata and statistics
+ * - Browsing events and market groupings
+ *
+ * For orderbook data and trading, use {@link ClobApiClient} and {@link TradingClient}.
+ *
+ * @example
+ * ```typescript
+ * const client = new GammaApiClient(rateLimiter, cache);
+ *
+ * // Find top volume markets
+ * const trending = await client.getTrendingMarkets(20);
+ * for (const market of trending) {
+ *   console.log(market.question, '$' + market.volume24hr.toLocaleString());
+ * }
+ * ```
+ */
+export class GammaApiClient {
+    rateLimiter;
+    cache;
+    /**
+     * Creates a new Gamma API client
+     *
+     * @param rateLimiter - Rate limiter instance for API throttling
+     * @param cache - Cache instance for storing data (supports both legacy Cache and CacheAdapter)
+     */
+    constructor(rateLimiter, cache) {
+        this.rateLimiter = rateLimiter;
+        this.cache = cache;
+    }
+    // ===== Market Queries =====
+    /**
+     * Get markets with optional filters and sorting
+     *
+     * @param params - Search and filter parameters
+     * @returns Array of markets matching the criteria
+     *
+     * @remarks
+     * Common sort fields:
+     * - `volume24hr` - 24-hour trading volume
+     * - `liquidity` - Available liquidity
+     * - `endDate` - Market end date
+     * - `volume` - Lifetime volume
+     *
+     * @example
+     * ```typescript
+     * // Get active markets sorted by 24h volume
+     * const markets = await client.getMarkets({
+     *   active: true,
+     *   closed: false,
+     *   order: 'volume24hr',
+     *   ascending: false,
+     *   limit: 50,
+     * });
+     *
+     * // Search by slug
+     * const market = await client.getMarkets({
+     *   slug: 'will-btc-reach-100k',
+     *   limit: 1,
+     * });
+     * ```
+     */
+    async getMarkets(params) {
+        const query = new URLSearchParams();
+        if (params?.slug)
+            query.set('slug', params.slug);
+        if (params?.conditionId)
+            query.set('condition_id', params.conditionId);
+        if (params?.active !== undefined)
+            query.set('active', String(params.active));
+        if (params?.closed !== undefined)
+            query.set('closed', String(params.closed));
+        if (params?.limit)
+            query.set('limit', String(params.limit));
+        if (params?.offset)
+            query.set('offset', String(params.offset));
+        if (params?.order)
+            query.set('order', params.order);
+        if (params?.ascending !== undefined)
+            query.set('ascending', String(params.ascending));
+        return this.rateLimiter.execute(ApiType.GAMMA_API, async () => {
+            const response = await fetch(`${GAMMA_API_BASE}/markets?${query}`);
+            if (!response.ok)
+                throw PolymarketError.fromHttpError(response.status, await response.json().catch(() => null));
+            const data = (await response.json());
+            if (!Array.isArray(data))
+                return [];
+            return data.map((item) => this.normalizeMarket(item));
+        });
+    }
+    /**
+     * Get a single market by its URL slug
+     *
+     * @param slug - The URL-friendly market slug
+     * @returns The market if found, null otherwise
+     *
+     * @example
+     * ```typescript
+     * const market = await client.getMarketBySlug('will-btc-reach-100k');
+     * if (market) {
+     *   console.log(market.question);
+     * }
+     * ```
+     */
+    async getMarketBySlug(slug) {
+        const markets = await this.getMarkets({ slug, limit: 1 });
+        return markets[0] || null;
+    }
+    /**
+     * Get a single market by condition ID
+     *
+     * @param conditionId - The unique condition identifier
+     * @returns The market if found, null otherwise
+     *
+     * @remarks
+     * For more reliable market data by condition ID, prefer {@link ClobApiClient.getMarket}.
+     *
+     * @example
+     * ```typescript
+     * const market = await client.getMarketByConditionId('0x82ace55...');
+     * ```
+     */
+    async getMarketByConditionId(conditionId) {
+        const markets = await this.getMarkets({ conditionId, limit: 1 });
+        return markets[0] || null;
+    }
+    // ===== Event Queries =====
+    /**
+     * Get events with optional filters
+     *
+     * @param params - Filter parameters
+     * @param params.slug - Filter by event slug
+     * @param params.active - Filter by active status
+     * @param params.limit - Maximum results to return
+     * @returns Array of events matching the criteria
+     *
+     * @example
+     * ```typescript
+     * // Get all active events
+     * const events = await client.getEvents({ active: true, limit: 20 });
+     *
+     * // Get a specific event by slug
+     * const election = await client.getEvents({ slug: '2024-us-election' });
+     * ```
+     */
+    async getEvents(params) {
+        const query = new URLSearchParams();
+        if (params?.slug)
+            query.set('slug', params.slug);
+        if (params?.active !== undefined)
+            query.set('active', String(params.active));
+        if (params?.limit)
+            query.set('limit', String(params.limit));
+        return this.rateLimiter.execute(ApiType.GAMMA_API, async () => {
+            const response = await fetch(`${GAMMA_API_BASE}/events?${query}`);
+            if (!response.ok)
+                throw PolymarketError.fromHttpError(response.status, await response.json().catch(() => null));
+            const data = (await response.json());
+            if (!Array.isArray(data))
+                return [];
+            return data.map((item) => this.normalizeEvent(item));
+        });
+    }
+    /**
+     * Get a single event by its URL slug
+     *
+     * @param slug - The URL-friendly event slug
+     * @returns The event if found, null otherwise
+     *
+     * @example
+     * ```typescript
+     * const event = await client.getEventBySlug('2024-us-election');
+     * if (event) {
+     *   console.log(`${event.title} has ${event.markets.length} markets`);
+     * }
+     * ```
+     */
+    async getEventBySlug(slug) {
+        const events = await this.getEvents({ slug, limit: 1 });
+        return events[0] || null;
+    }
+    /**
+     * Get a single event by its ID
+     *
+     * @param id - The internal event ID
+     * @returns The event if found, null otherwise
+     *
+     * @example
+     * ```typescript
+     * const event = await client.getEventById('12345');
+     * ```
+     */
+    async getEventById(id) {
+        return this.rateLimiter.execute(ApiType.GAMMA_API, async () => {
+            const response = await fetch(`${GAMMA_API_BASE}/events/${id}`);
+            if (!response.ok) {
+                if (response.status === 404)
+                    return null;
+                throw PolymarketError.fromHttpError(response.status, await response.json().catch(() => null));
+            }
+            const data = (await response.json());
+            return this.normalizeEvent(data);
+        });
+    }
+    // ===== Trending =====
+    /**
+     * Get trending markets sorted by 24-hour volume
+     *
+     * @param limit - Maximum number of markets to return (default: 20)
+     * @returns Array of active markets sorted by volume
+     *
+     * @remarks
+     * This is a convenience method equivalent to:
+     * ```typescript
+     * getMarkets({
+     *   active: true,
+     *   closed: false,
+     *   order: 'volume24hr',
+     *   ascending: false,
+     *   limit,
+     * })
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Get top 10 trending markets
+     * const trending = await client.getTrendingMarkets(10);
+     *
+     * for (const market of trending) {
+     *   console.log(`${market.question}`);
+     *   console.log(`  24h Volume: $${market.volume24hr?.toLocaleString()}`);
+     *   console.log(`  YES Price: ${(market.outcomePrices[0] * 100).toFixed(1)}%`);
+     * }
+     * ```
+     */
+    async getTrendingMarkets(limit = 20) {
+        return this.getMarkets({
+            active: true,
+            closed: false,
+            order: 'volume24hr',
+            ascending: false,
+            limit,
+        });
+    }
+    // ===== Data Normalization =====
+    normalizeMarket(m) {
+        return {
+            id: String(m.id || ''),
+            conditionId: String(m.conditionId || ''),
+            slug: String(m.slug || ''),
+            question: String(m.question || ''),
+            description: m.description ? String(m.description) : undefined,
+            outcomes: this.parseJsonArray(m.outcomes, ['Yes', 'No']),
+            outcomePrices: this.parseJsonArray(m.outcomePrices, [0.5, 0.5]).map(Number),
+            volume: Number(m.volume || 0),
+            volume24hr: m.volume24hr !== undefined ? Number(m.volume24hr) : undefined,
+            volume1wk: m.volume1wk !== undefined ? Number(m.volume1wk) : undefined,
+            liquidity: Number(m.liquidity || 0),
+            spread: m.spread !== undefined ? Number(m.spread) : undefined,
+            oneDayPriceChange: m.oneDayPriceChange !== undefined
+                ? Number(m.oneDayPriceChange)
+                : undefined,
+            oneWeekPriceChange: m.oneWeekPriceChange !== undefined
+                ? Number(m.oneWeekPriceChange)
+                : undefined,
+            lastTradePrice: m.lastTradePrice !== undefined ? Number(m.lastTradePrice) : undefined,
+            bestBid: m.bestBid !== undefined ? Number(m.bestBid) : undefined,
+            bestAsk: m.bestAsk !== undefined ? Number(m.bestAsk) : undefined,
+            endDate: new Date(String(m.endDate || Date.now())),
+            active: Boolean(m.active),
+            closed: Boolean(m.closed),
+            image: m.image ? String(m.image) : undefined,
+            icon: m.icon ? String(m.icon) : undefined,
+            tags: m.tags ? this.parseJsonArray(m.tags, []) : undefined,
+        };
+    }
+    normalizeEvent(e) {
+        const markets = e.markets;
+        return {
+            id: String(e.id || ''),
+            slug: String(e.slug || ''),
+            title: String(e.title || ''),
+            description: e.description ? String(e.description) : undefined,
+            markets: Array.isArray(markets)
+                ? markets.map((m) => this.normalizeMarket(m))
+                : [],
+            startDate: e.startDate ? new Date(String(e.startDate)) : undefined,
+            endDate: e.endDate ? new Date(String(e.endDate)) : undefined,
+            image: e.image ? String(e.image) : undefined,
+        };
+    }
+    parseJsonArray(value, fallback) {
+        if (Array.isArray(value))
+            return value;
+        if (typeof value === 'string') {
+            try {
+                return JSON.parse(value);
+            }
+            catch {
+                return fallback;
+            }
+        }
+        return fallback;
+    }
+}
+//# sourceMappingURL=gamma-api.js.map

package/dist/clients/gamma-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gamma-api.js","sourceRoot":"","sources":["../../src/clients/gamma-api.ts"],"names":[],"mappings":"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"}

package/dist/clients/trading-client.d.ts

@@ -0,0 +1,252 @@
+/**
+ * Trading Client for Polymarket
+ *
+ * Wraps @polymarket/clob-client for order execution:
+ * - Create/cancel orders
+ * - Market/limit orders
+ * - Order management
+ *
+ * Based on: docs/01-product-research/06-poly-sdk/reports/02-clob-client.md
+ */
+import { ClobClient, type TickSize } from '@polymarket/clob-client';
+import { RateLimiter } from '../core/rate-limiter.js';
+export declare const POLYGON_MAINNET = 137;
+export declare const POLYGON_AMOY = 80002;
+export type Side = 'BUY' | 'SELL';
+export type OrderType = 'GTC' | 'FOK' | 'GTD' | 'FAK';
+export interface ApiCredentials {
+    key: string;
+    secret: string;
+    passphrase: string;
+}
+export interface OrderParams {
+    /** Token ID to trade */
+    tokenId: string;
+    /** BUY or SELL */
+    side: Side;
+    /** Price (0.001 - 0.999) */
+    price: number;
+    /** Size in shares */
+    size: number;
+    /** Order type: GTC (default) or GTD for limit orders */
+    orderType?: 'GTC' | 'GTD';
+    /** Expiration for GTD orders (unix timestamp seconds) */
+    expiration?: number;
+}
+export interface MarketOrderParams {
+    /** Token ID to trade */
+    tokenId: string;
+    /** BUY or SELL */
+    side: Side;
+    /** Amount in USDC for BUY, shares for SELL */
+    amount: number;
+    /** Price limit (optional) */
+    price?: number;
+    /** Order type: FOK (default) or FAK */
+    orderType?: 'FOK' | 'FAK';
+}
+export interface Order {
+    id: string;
+    status: string;
+    tokenId: string;
+    side: Side;
+    price: number;
+    originalSize: number;
+    filledSize: number;
+    remainingSize: number;
+    associateTrades: string[];
+    createdAt: number;
+}
+export interface OrderResult {
+    success: boolean;
+    orderId?: string;
+    orderIds?: string[];
+    errorMsg?: string;
+    transactionHashes?: string[];
+}
+export interface TradeInfo {
+    id: string;
+    tokenId: string;
+    side: Side;
+    price: number;
+    size: number;
+    fee: number;
+    timestamp: number;
+}
+export interface UserEarning {
+    date: string;
+    conditionId: string;
+    assetAddress: string;
+    makerAddress: string;
+    earnings: number;
+    assetRate: number;
+}
+export interface MarketReward {
+    conditionId: string;
+    question: string;
+    marketSlug: string;
+    eventSlug: string;
+    image: string;
+    rewardsMaxSpread: number;
+    rewardsMinSize: number;
+    tokens: Array<{
+        tokenId: string;
+        outcome: string;
+        price: number;
+    }>;
+    rewardsConfig: Array<{
+        assetAddress: string;
+        startDate: string;
+        endDate: string;
+        ratePerDay: number;
+        totalRewards: number;
+    }>;
+}
+export interface OrderScoring {
+    scoring: boolean;
+}
+export interface TradingClientConfig {
+    /** Private key for signing */
+    privateKey: string;
+    /** Chain ID (default: Polygon mainnet 137) */
+    chainId?: number;
+    /** Pre-generated API credentials (optional) */
+    credentials?: ApiCredentials;
+}
+export declare class TradingClient {
+    private rateLimiter;
+    private config;
+    private clobClient;
+    private wallet;
+    private chainId;
+    private credentials;
+    private initialized;
+    private tickSizeCache;
+    private negRiskCache;
+    constructor(rateLimiter: RateLimiter, config: TradingClientConfig);
+    /**
+     * Initialize the trading client
+     * Creates API credentials if not provided
+     */
+    initialize(): Promise<void>;
+    private ensureInitialized;
+    /**
+     * Get tick size for a token (cached)
+     */
+    getTickSize(tokenId: string): Promise<TickSize>;
+    /**
+     * Check if token is neg risk (cached)
+     */
+    isNegRisk(tokenId: string): Promise<boolean>;
+    /**
+     * Create and post a limit order (single step)
+     */
+    createOrder(params: OrderParams): Promise<OrderResult>;
+    /**
+     * Create and post a market order (executes at best available price)
+     */
+    createMarketOrder(params: MarketOrderParams): Promise<OrderResult>;
+    /**
+     * Cancel an order by ID
+     */
+    cancelOrder(orderId: string): Promise<OrderResult>;
+    /**
+     * Cancel multiple orders by IDs (order hashes)
+     */
+    cancelOrders(orderIds: string[]): Promise<OrderResult>;
+    /**
+     * Cancel all open orders
+     */
+    cancelAllOrders(): Promise<OrderResult>;
+    /**
+     * Get open orders (fully paginated)
+     */
+    getOpenOrders(marketId?: string): Promise<Order[]>;
+    /**
+     * Get trade history
+     */
+    getTrades(marketId?: string): Promise<TradeInfo[]>;
+    /**
+     * Get current price for a token
+     */
+    getPrice(tokenId: string, side: Side): Promise<number>;
+    /**
+     * Get midpoint price for a token
+     */
+    getMidpoint(tokenId: string): Promise<number>;
+    /**
+     * Get spread for a token
+     */
+    getSpread(tokenId: string): Promise<number>;
+    /**
+     * Get wallet address
+     */
+    getAddress(): string;
+    /**
+     * Get API credentials (for storage/reuse)
+     */
+    getCredentials(): ApiCredentials | null;
+    /**
+     * Check if client is initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Get underlying CLOB client for advanced usage
+     */
+    getClobClient(): ClobClient | null;
+    /**
+     * Check if an order is scoring for rewards
+     * Orders that are scoring contribute to daily reward earnings
+     */
+    isOrderScoring(orderId: string): Promise<boolean>;
+    /**
+     * Check if multiple orders are scoring for rewards
+     */
+    areOrdersScoring(orderIds: string[]): Promise<Record<string, boolean>>;
+    /**
+     * Get user earnings for a specific day
+     * @param date - Date in YYYY-MM-DD format
+     */
+    getEarningsForDay(date: string): Promise<UserEarning[]>;
+    /**
+     * Get total earnings across all markets for a specific day
+     * @param date - Date in YYYY-MM-DD format
+     */
+    getTotalEarningsForDay(date: string): Promise<{
+        date: string;
+        totalEarnings: number;
+        byAsset: Array<{
+            assetAddress: string;
+            earnings: number;
+            rate: number;
+        }>;
+    }>;
+    /**
+     * Get current market rewards configuration
+     * Returns markets that have active reward programs
+     */
+    getCurrentRewards(): Promise<MarketReward[]>;
+    /**
+     * Get reward percentages by market
+     * Higher percentages indicate higher reward rates
+     */
+    getRewardPercentages(): Promise<Record<string, number>>;
+    /**
+     * Get raw rewards for a specific market
+     */
+    getMarketRewards(conditionId: string): Promise<MarketReward[]>;
+    /**
+     * Get balance and allowance for collateral or conditional tokens
+     * @param assetType - 'COLLATERAL' for USDC, 'CONDITIONAL' for outcome tokens
+     * @param tokenId - Token ID (required for CONDITIONAL type)
+     */
+    getBalanceAllowance(assetType: 'COLLATERAL' | 'CONDITIONAL', tokenId?: string): Promise<{
+        balance: string;
+        allowance: string;
+    }>;
+    /**
+     * Update balance allowance (approve spending)
+     */
+    updateBalanceAllowance(assetType: 'COLLATERAL' | 'CONDITIONAL', tokenId?: string): Promise<void>;
+}
+//# sourceMappingURL=trading-client.d.ts.map

package/dist/clients/trading-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trading-client.d.ts","sourceRoot":"","sources":["../../src/clients/trading-client.ts"],"names":[],"mappings":"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"}