@catalyst-team/poly-sdk 0.2.1 → 0.4.0

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

@@ -0,0 +1,359 @@
+/**
+ * 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 '@catalyst-team/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));
+        if (params?.tag)
+            query.set('tag', params.tag);
+        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())),
+            createdAt: m.createdAt ? new Date(String(m.createdAt)) : undefined,
+            startDate: m.startDate ? new Date(String(m.startDate)) : undefined,
+            acceptingOrdersTimestamp: m.acceptingOrdersTimestamp
+                ? new Date(String(m.acceptingOrdersTimestamp))
+                : undefined,
+            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/src/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/src/clients/subgraph.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Polymarket Subgraph Client
+ *
+ * 官方文档: https://docs.polymarket.com/developers/subgraph/overview
+ * Schema 仓库: https://github.com/Polymarket/polymarket-subgraph
+ *
+ * 5 个 Subgraph:
+ * - Positions (0.0.7): 用户余额、Net 余额
+ * - PnL (0.0.14): 用户持仓、PnL、Condition 结算状态
+ * - Activity (0.0.4): Split/Merge/Redemption 事件
+ * - OI (0.0.6): 市场/全局 Open Interest
+ * - Orderbook (0.0.1): 订单成交事件
+ */
+import { RateLimiter } from '../core/rate-limiter.js';
+import type { UnifiedCache } from '../core/unified-cache.js';
+export declare const SUBGRAPH_ENDPOINTS: {
+    readonly positions: "https://api.goldsky.com/api/public/project_cl6mb8i9h0003e201j6li0diw/subgraphs/positions-subgraph/0.0.7/gn";
+    readonly pnl: "https://api.goldsky.com/api/public/project_cl6mb8i9h0003e201j6li0diw/subgraphs/pnl-subgraph/0.0.14/gn";
+    readonly activity: "https://api.goldsky.com/api/public/project_cl6mb8i9h0003e201j6li0diw/subgraphs/activity-subgraph/0.0.4/gn";
+    readonly oi: "https://api.goldsky.com/api/public/project_cl6mb8i9h0003e201j6li0diw/subgraphs/oi-subgraph/0.0.6/gn";
+    readonly orderbook: "https://api.goldsky.com/api/public/project_cl6mb8i9h0003e201j6li0diw/subgraphs/orderbook-subgraph/0.0.1/gn";
+};
+export type SubgraphName = keyof typeof SUBGRAPH_ENDPOINTS;
+export interface UserBalance {
+    id: string;
+    user: string;
+    asset: string;
+    balance: string;
+}
+export interface NetUserBalance {
+    id: string;
+    user: string;
+    asset: string;
+    balance: string;
+}
+export interface UserPosition {
+    id: string;
+    user: string;
+    tokenId: string;
+    amount: string;
+    avgPrice: string;
+    realizedPnl: string;
+    totalBought: string;
+}
+export interface Condition {
+    id: string;
+    positionIds: string[];
+    payoutNumerators: string[];
+    payoutDenominator: string;
+}
+export interface Split {
+    id: string;
+    timestamp: string;
+    stakeholder: string;
+    condition: string;
+    amount: string;
+}
+export interface Merge {
+    id: string;
+    timestamp: string;
+    stakeholder: string;
+    condition: string;
+    amount: string;
+}
+export interface Redemption {
+    id: string;
+    timestamp: string;
+    redeemer: string;
+    condition: string;
+    payout: string;
+}
+export interface MarketOpenInterest {
+    id: string;
+    amount: string;
+}
+export interface GlobalOpenInterest {
+    id: string;
+    amount: string;
+}
+export interface OrderFilledEvent {
+    id: string;
+    transactionHash: string;
+    timestamp: string;
+    orderHash: string;
+    maker: string;
+    taker: string;
+    makerAssetId: string;
+    takerAssetId: string;
+    makerAmountFilled: string;
+    takerAmountFilled: string;
+    fee: string;
+}
+export interface MarketData {
+    id: string;
+    volume: string;
+}
+export interface SubgraphQueryParams {
+    first?: number;
+    skip?: number;
+    orderBy?: string;
+    orderDirection?: 'asc' | 'desc';
+    where?: Record<string, unknown>;
+}
+export declare class SubgraphClient {
+    private rateLimiter;
+    private cache;
+    constructor(rateLimiter: RateLimiter, cache: UnifiedCache);
+    /**
+     * 执行 GraphQL 查询
+     */
+    private query;
+    /**
+     * 构建查询字符串
+     */
+    private buildQuery;
+    /**
+     * 获取用户余额
+     */
+    getUserBalances(user: string, params?: SubgraphQueryParams): Promise<UserBalance[]>;
+    /**
+     * 获取 Net 用户余额
+     */
+    getNetUserBalances(user: string, params?: SubgraphQueryParams): Promise<NetUserBalance[]>;
+    /**
+     * 获取用户持仓 (含 PnL)
+     */
+    getUserPositions(user: string, params?: SubgraphQueryParams): Promise<UserPosition[]>;
+    /**
+     * 获取 Condition 结算状态
+     */
+    getConditions(params?: SubgraphQueryParams): Promise<Condition[]>;
+    /**
+     * 获取单个 Condition
+     */
+    getCondition(conditionId: string): Promise<Condition | null>;
+    /**
+     * 检查 Condition 是否已结算
+     */
+    isConditionResolved(conditionId: string): Promise<boolean>;
+    /**
+     * 获取用户的 Split 事件
+     */
+    getSplits(user: string, params?: SubgraphQueryParams): Promise<Split[]>;
+    /**
+     * 获取用户的 Merge 事件
+     */
+    getMerges(user: string, params?: SubgraphQueryParams): Promise<Merge[]>;
+    /**
+     * 获取用户的 Redemption 事件
+     */
+    getRedemptions(user: string, params?: SubgraphQueryParams): Promise<Redemption[]>;
+    /**
+     * 获取最近的 Redemption 事件 (不限用户)
+     */
+    getRecentRedemptions(params?: SubgraphQueryParams): Promise<Redemption[]>;
+    /**
+     * 获取市场 Open Interest
+     */
+    getMarketOpenInterest(conditionId: string): Promise<MarketOpenInterest | null>;
+    /**
+     * 获取 Top 市场按 OI 排序
+     */
+    getTopMarketsByOI(params?: SubgraphQueryParams): Promise<MarketOpenInterest[]>;
+    /**
+     * 获取全局 Open Interest
+     */
+    getGlobalOpenInterest(): Promise<string>;
+    /**
+     * 获取订单成交事件
+     */
+    getOrderFilledEvents(params?: SubgraphQueryParams): Promise<OrderFilledEvent[]>;
+    /**
+     * 获取用户作为 maker 的成交事件
+     */
+    getMakerFills(maker: string, params?: SubgraphQueryParams): Promise<OrderFilledEvent[]>;
+    /**
+     * 获取用户作为 taker 的成交事件
+     */
+    getTakerFills(taker: string, params?: SubgraphQueryParams): Promise<OrderFilledEvent[]>;
+    /**
+     * 获取市场数据
+     */
+    getMarketData(assetId: string): Promise<MarketData | null>;
+    /**
+     * 获取用户完整的链上活动摘要
+     */
+    getUserActivitySummary(user: string): Promise<{
+        positions: UserPosition[];
+        splits: Split[];
+        merges: Merge[];
+        redemptions: Redemption[];
+        makerFills: OrderFilledEvent[];
+        takerFills: OrderFilledEvent[];
+    }>;
+}
+//# sourceMappingURL=subgraph.d.ts.map

package/dist/src/clients/subgraph.d.ts.map

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