@catalyst-team/poly-sdk 0.2.0 → 0.2.1

package/dist/utils/price-utils.js

@@ -0,0 +1,236 @@
+/**
+ * Price Utilities for Polymarket Trading
+ *
+ * Provides helpers for:
+ * - Price validation and rounding to tick size
+ * - Size validation
+ * - Order amount calculation
+ */
+// Rounding configuration for each tick size
+export const ROUNDING_CONFIG = {
+    '0.1': { price: 1, size: 2, amount: 2 },
+    '0.01': { price: 2, size: 2, amount: 4 },
+    '0.001': { price: 3, size: 2, amount: 5 },
+    '0.0001': { price: 4, size: 2, amount: 6 },
+};
+/**
+ * Round a price to the appropriate tick size
+ *
+ * @param price - The price to round (0 to 1)
+ * @param tickSize - The tick size for the market
+ * @param direction - 'floor' for sells, 'ceil' for buys, 'round' for midpoint
+ * @returns Rounded price
+ *
+ * @example
+ * roundPrice(0.523, '0.01', 'floor') // 0.52
+ * roundPrice(0.523, '0.01', 'ceil') // 0.53
+ */
+export function roundPrice(price, tickSize, direction = 'round') {
+    const decimals = ROUNDING_CONFIG[tickSize].price;
+    const multiplier = Math.pow(10, decimals);
+    let rounded;
+    switch (direction) {
+        case 'floor':
+            rounded = Math.floor(price * multiplier) / multiplier;
+            break;
+        case 'ceil':
+            rounded = Math.ceil(price * multiplier) / multiplier;
+            break;
+        default:
+            rounded = Math.round(price * multiplier) / multiplier;
+    }
+    // Clamp to valid price range
+    return Math.max(0.001, Math.min(0.999, rounded));
+}
+/**
+ * Round a size to valid decimals (always 2 decimal places)
+ */
+export function roundSize(size) {
+    return Math.round(size * 100) / 100;
+}
+/**
+ * Validate a price is within valid range and tick size
+ *
+ * @param price - The price to validate
+ * @param tickSize - The tick size for the market
+ * @returns Validation result with error message if invalid
+ */
+export function validatePrice(price, tickSize) {
+    // Check range
+    if (price < 0.001 || price > 0.999) {
+        return { valid: false, error: 'Price must be between 0.001 and 0.999' };
+    }
+    // Check tick size alignment
+    const decimals = ROUNDING_CONFIG[tickSize].price;
+    const multiplier = Math.pow(10, decimals);
+    const rounded = Math.round(price * multiplier) / multiplier;
+    if (Math.abs(price - rounded) > 1e-10) {
+        return {
+            valid: false,
+            error: `Price ${price} does not align with tick size ${tickSize}. Use ${rounded} instead.`,
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Validate minimum size requirements
+ *
+ * @param size - The size to validate
+ * @param minOrderSize - Minimum order size from market config (usually 0.1)
+ */
+export function validateSize(size, minOrderSize = 0.1) {
+    if (size < minOrderSize) {
+        return {
+            valid: false,
+            error: `Size ${size} is below minimum order size ${minOrderSize}`,
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Calculate the amount needed for a buy order (in USDC)
+ *
+ * @param price - Price per share
+ * @param size - Number of shares to buy
+ * @returns Amount in USDC
+ */
+export function calculateBuyAmount(price, size) {
+    return price * size;
+}
+/**
+ * Calculate the payout for a sell order (in USDC)
+ *
+ * @param price - Price per share
+ * @param size - Number of shares to sell
+ * @returns Amount in USDC
+ */
+export function calculateSellPayout(price, size) {
+    return price * size;
+}
+/**
+ * Calculate number of shares that can be bought with a given amount
+ *
+ * @param amount - USDC amount to spend
+ * @param price - Price per share
+ * @returns Number of shares
+ */
+export function calculateSharesForAmount(amount, price) {
+    return roundSize(amount / price);
+}
+/**
+ * Calculate the spread between bid and ask
+ *
+ * @param bid - Highest bid price
+ * @param ask - Lowest ask price
+ * @returns Spread as a decimal (0 to 1)
+ */
+export function calculateSpread(bid, ask) {
+    return ask - bid;
+}
+/**
+ * Calculate the midpoint price between bid and ask
+ *
+ * @param bid - Highest bid price
+ * @param ask - Lowest ask price
+ * @returns Midpoint price
+ */
+export function calculateMidpoint(bid, ask) {
+    return (bid + ask) / 2;
+}
+/**
+ * 计算有效价格（考虑 Polymarket 订单簿的镜像特性）
+ *
+ * Polymarket 的关键特性：买 YES @ P = 卖 NO @ (1-P)
+ * 因此同一订单会在两个订单簿中出现
+ *
+ * 有效价格是考虑镜像后的最优价格
+ *
+ * @param yesAsk - YES token 的最低卖价
+ * @param yesBid - YES token 的最高买价
+ * @param noAsk - NO token 的最低卖价
+ * @param noBid - NO token 的最高买价
+ */
+export function getEffectivePrices(yesAsk, yesBid, noAsk, noBid) {
+    return {
+        // 买 YES: 直接买 YES.ask 或 通过卖 NO (成本 = 1 - NO.bid)
+        effectiveBuyYes: Math.min(yesAsk, 1 - noBid),
+        // 买 NO: 直接买 NO.ask 或 通过卖 YES (成本 = 1 - YES.bid)
+        effectiveBuyNo: Math.min(noAsk, 1 - yesBid),
+        // 卖 YES: 直接卖 YES.bid 或 通过买 NO (收入 = 1 - NO.ask)
+        effectiveSellYes: Math.max(yesBid, 1 - noAsk),
+        // 卖 NO: 直接卖 NO.bid 或 通过买 YES (收入 = 1 - YES.ask)
+        effectiveSellNo: Math.max(noBid, 1 - yesAsk),
+    };
+}
+/**
+ * Check if there's an arbitrage opportunity
+ *
+ * 使用有效价格计算套利机会（正确考虑镜像订单）
+ *
+ * Long arb: Buy YES + Buy NO < 1 (使用有效买入价格)
+ * Short arb: Sell YES + Sell NO > 1 (使用有效卖出价格)
+ *
+ * 详细文档见: docs/01-polymarket-orderbook-arbitrage.md
+ *
+ * @param yesAsk - Lowest ask for YES token
+ * @param noAsk - Lowest ask for NO token
+ * @param yesBid - Highest bid for YES token
+ * @param noBid - Highest bid for NO token
+ * @returns Arbitrage info or null
+ */
+export function checkArbitrage(yesAsk, noAsk, yesBid, noBid) {
+    // 计算有效价格
+    const effective = getEffectivePrices(yesAsk, yesBid, noAsk, noBid);
+    // Long arbitrage: Buy complete set (YES + NO) cheaper than $1
+    const effectiveLongCost = effective.effectiveBuyYes + effective.effectiveBuyNo;
+    const longProfit = 1 - effectiveLongCost;
+    if (longProfit > 0) {
+        return {
+            type: 'long',
+            profit: longProfit,
+            description: `Buy YES @ ${effective.effectiveBuyYes.toFixed(4)} + NO @ ${effective.effectiveBuyNo.toFixed(4)}, Merge for $1`,
+        };
+    }
+    // Short arbitrage: Sell complete set (YES + NO) for more than $1
+    const effectiveShortRevenue = effective.effectiveSellYes + effective.effectiveSellNo;
+    const shortProfit = effectiveShortRevenue - 1;
+    if (shortProfit > 0) {
+        return {
+            type: 'short',
+            profit: shortProfit,
+            description: `Split $1, Sell YES @ ${effective.effectiveSellYes.toFixed(4)} + NO @ ${effective.effectiveSellNo.toFixed(4)}`,
+        };
+    }
+    return null;
+}
+/**
+ * Format price for display
+ */
+export function formatPrice(price, tickSize) {
+    const decimals = tickSize ? ROUNDING_CONFIG[tickSize].price : 4;
+    return price.toFixed(decimals);
+}
+/**
+ * Format amount in USDC
+ */
+export function formatUSDC(amount) {
+    return `$${amount.toFixed(2)}`;
+}
+/**
+ * Calculate PnL for a position
+ *
+ * @param entryPrice - Average entry price
+ * @param currentPrice - Current market price
+ * @param size - Position size
+ * @param side - 'long' for YES, 'short' for NO
+ */
+export function calculatePnL(entryPrice, currentPrice, size, side = 'long') {
+    const pnl = side === 'long'
+        ? (currentPrice - entryPrice) * size
+        : (entryPrice - currentPrice) * size;
+    const pnlPercent = side === 'long'
+        ? ((currentPrice - entryPrice) / entryPrice) * 100
+        : ((entryPrice - currentPrice) / entryPrice) * 100;
+    return { pnl, pnlPercent };
+}
+//# sourceMappingURL=price-utils.js.map

package/dist/utils/price-utils.js.map

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

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@catalyst-team/poly-sdk",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "private": false,
+  "license": "MIT",
   "description": "TypeScript SDK for Polymarket - prediction markets trading, smart money analysis, and market data",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,7 +22,11 @@
     "smart-money"
   ],
   "author": "Catalyst Team",
-  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
   "publishConfig": {
     "access": "public"
   },