@catalyst-team/poly-sdk 0.2.1 → 0.4.0

package/dist/src/index.js

@@ -0,0 +1,262 @@
+/**
+ * @catalyst-team/poly-sdk
+ *
+ * Unified SDK for Polymarket APIs
+ * - Data API (positions, activity, trades, leaderboard)
+ * - Gamma API (markets, events, trending)
+ * - CLOB API (orderbook, market info, trading)
+ * - Services (WalletService, MarketService)
+ */
+// Core infrastructure
+export { RateLimiter, ApiType } from './core/rate-limiter.js';
+export { Cache, CACHE_TTL } from './core/cache.js';
+export { PolymarketError, ErrorCode, withRetry } from './core/errors.js';
+export * from './core/types.js';
+export { createUnifiedCache } from './core/unified-cache.js';
+// API Clients
+export { DataApiClient } from './clients/data-api.js';
+export { GammaApiClient } from './clients/gamma-api.js';
+// ClobApiClient has been removed - use TradingService instead
+// TradingService provides getMarket(), getProcessedOrderbook(), etc.
+// Subgraph Client (on-chain data via Goldsky)
+export { SubgraphClient, SUBGRAPH_ENDPOINTS } from './clients/subgraph.js';
+// Services
+export { WalletService } from './services/wallet-service.js';
+export { MarketService, getIntervalMs as getIntervalMsService } from './services/market-service.js';
+// Real-time (V2 - using official @polymarket/real-time-data-client)
+export { RealtimeServiceV2 } from './services/realtime-service-v2.js';
+// RealtimeService (legacy) has been removed - use RealtimeServiceV2 instead
+// ArbitrageService (Real-time arbitrage detection, execution, rebalancing, and settlement)
+export { ArbitrageService } from './services/arbitrage-service.js';
+// SmartMoneyService - Smart Money detection and Copy Trading
+export { SmartMoneyService } from './services/smart-money-service.js';
+// DipArbService - Dip Arbitrage for 15m/5m UP/DOWN markets
+export { DipArbService } from './services/dip-arb-service.js';
+// BinanceService - BTC/ETH/SOL K-line data from Binance
+export { BinanceService } from './services/binance-service.js';
+// TradingService - Unified trading and market data
+export { TradingService, POLYGON_MAINNET, POLYGON_AMOY, 
+// Polymarket order minimum requirements
+MIN_ORDER_VALUE_USDC, MIN_ORDER_SIZE_SHARES, } from './services/trading-service.js';
+// TradingClient (legacy) has been removed - use TradingService instead
+// TradingService provides all trading functionality with proper type exports
+// CTF (Conditional Token Framework)
+// NOTE: USDC_CONTRACT is USDC.e (bridged), required for Polymarket CTF
+// NATIVE_USDC_CONTRACT is native USDC, NOT compatible with CTF
+export { CTFClient, CTF_CONTRACT, USDC_CONTRACT, // USDC.e (0x2791...) - Required for CTF
+NATIVE_USDC_CONTRACT, // Native USDC (0x3c49...) - NOT for CTF
+NEG_RISK_CTF_EXCHANGE, NEG_RISK_ADAPTER, USDC_DECIMALS, calculateConditionId, parseUsdc, formatUsdc, } from './clients/ctf-client.js';
+export { RevertReason } from './clients/ctf-client.js';
+// Bridge (Cross-chain Deposits)
+export { BridgeClient, SUPPORTED_CHAINS, BRIDGE_TOKENS, estimateBridgeOutput, getExplorerUrl, depositUsdc, swapAndDeposit, getSupportedDepositTokens, } from './clients/bridge-client.js';
+// Swap Service (DEX swaps on Polygon)
+export { SwapService, QUICKSWAP_ROUTER, POLYGON_TOKENS, TOKEN_DECIMALS, } from './services/swap-service.js';
+// Authorization (ERC20/ERC1155 Approvals)
+export { AuthorizationService } from './services/authorization-service.js';
+// OnchainService (Unified on-chain operations: CTF + Authorization + Swaps)
+export { OnchainService } from './services/onchain-service.js';
+// Price Utilities
+export { roundPrice, roundSize, validatePrice, validateSize, calculateBuyAmount, calculateSellPayout, calculateSharesForAmount, calculateSpread, calculateMidpoint, formatPrice, formatUSDC, calculatePnL, checkArbitrage, getEffectivePrices, ROUNDING_CONFIG, } from './utils/price-utils.js';
+// NOTE: MCP tools have been moved to @catalyst-team/poly-mcp package
+// See packages/poly-mcp/
+// ===== Main SDK Class =====
+import { RateLimiter } from './core/rate-limiter.js';
+import { DataApiClient } from './clients/data-api.js';
+import { GammaApiClient } from './clients/gamma-api.js';
+import { SubgraphClient } from './clients/subgraph.js';
+import { WalletService } from './services/wallet-service.js';
+import { MarketService } from './services/market-service.js';
+import { TradingService } from './services/trading-service.js';
+import { RealtimeServiceV2 } from './services/realtime-service-v2.js';
+import { SmartMoneyService } from './services/smart-money-service.js';
+import { BinanceService } from './services/binance-service.js';
+import { DipArbService } from './services/dip-arb-service.js';
+import { createUnifiedCache } from './core/unified-cache.js';
+export class PolymarketSDK {
+    // Infrastructure
+    rateLimiter;
+    cache;
+    // API Clients
+    dataApi;
+    gammaApi;
+    tradingService;
+    subgraph;
+    // Services
+    wallets;
+    markets;
+    realtime;
+    smartMoney;
+    binance;
+    dipArb;
+    // Initialization state
+    _initialized = false;
+    constructor(config = {}) {
+        // Initialize infrastructure
+        this.rateLimiter = new RateLimiter();
+        // Create unified cache (supports both legacy Cache and CacheAdapter)
+        this.cache = createUnifiedCache(config.cache);
+        // Initialize API clients
+        this.dataApi = new DataApiClient(this.rateLimiter, this.cache);
+        this.gammaApi = new GammaApiClient(this.rateLimiter, this.cache);
+        // TradingService requires a private key - use provided key or dummy key for read-only
+        const privateKey = config.privateKey || '0x' + '1'.repeat(64);
+        this.tradingService = new TradingService(this.rateLimiter, this.cache, {
+            privateKey,
+            chainId: config.chainId,
+            credentials: config.creds,
+        });
+        this.subgraph = new SubgraphClient(this.rateLimiter, this.cache);
+        // Initialize services
+        this.wallets = new WalletService(this.dataApi, this.subgraph, this.cache);
+        this.binance = new BinanceService(this.rateLimiter, this.cache);
+        this.markets = new MarketService(this.gammaApi, this.dataApi, this.rateLimiter, this.cache, undefined, this.binance);
+        this.realtime = new RealtimeServiceV2();
+        this.smartMoney = new SmartMoneyService(this.wallets, this.realtime, this.tradingService);
+        // Initialize DipArbService
+        this.dipArb = new DipArbService(this.realtime, this.tradingService, this.markets, config.privateKey, config.chainId);
+    }
+    // ===== Static Factory Methods =====
+    /**
+     * Create and initialize SDK in one call
+     *
+     * @example
+     * ```typescript
+     * const sdk = await PolymarketSDK.create({ privateKey: '...' });
+     * // Ready to trade and track smart money
+     * ```
+     */
+    static async create(config = {}) {
+        const sdk = new PolymarketSDK(config);
+        await sdk.start();
+        return sdk;
+    }
+    // ===== Lifecycle Methods =====
+    /**
+     * Initialize the SDK (required for trading operations)
+     */
+    async initialize() {
+        if (this._initialized)
+            return;
+        await this.tradingService.initialize();
+        this._initialized = true;
+    }
+    /**
+     * Check if SDK is initialized
+     */
+    isInitialized() {
+        return this._initialized;
+    }
+    /**
+     * Start SDK - initialize trading + connect WebSocket
+     *
+     * One method to do everything:
+     * - Initialize trading service (derive API credentials)
+     * - Connect WebSocket
+     * - Wait for connection
+     *
+     * @example
+     * ```typescript
+     * const sdk = new PolymarketSDK({ privateKey: '...' });
+     * await sdk.start();
+     * // Ready to use
+     * ```
+     */
+    async start(options = {}) {
+        await this.initialize();
+        this.connect();
+        await this.waitForConnection(options.timeout ?? 10000);
+    }
+    /**
+     * Connect to realtime WebSocket (required for smart money tracking)
+     */
+    connect() {
+        this.realtime.connect();
+    }
+    /**
+     * Wait for WebSocket connection
+     */
+    async waitForConnection(timeoutMs = 10000) {
+        // Already connected
+        if (this.realtime.isConnected?.()) {
+            return;
+        }
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => reject(new Error('Connection timeout')), timeoutMs);
+            this.realtime.once('connected', () => {
+                clearTimeout(timeout);
+                resolve();
+            });
+        });
+    }
+    /**
+     * Stop SDK - disconnect all services and clean up
+     */
+    stop() {
+        this.dipArb.stop();
+        this.smartMoney.disconnect();
+        this.realtime.disconnect();
+    }
+    /**
+     * Disconnect all services and clean up
+     * @deprecated Use stop() instead
+     */
+    disconnect() {
+        this.stop();
+    }
+    // ===== Unified Market Access =====
+    /**
+     * Get market by slug or condition ID
+     * Delegates to MarketService which handles merging Gamma and CLOB data
+     */
+    async getMarket(identifier) {
+        return this.markets.getMarket(identifier);
+    }
+    // ===== Orderbook Analysis =====
+    /**
+     * Get processed orderbook with analytics
+     */
+    async getOrderbook(conditionId) {
+        return this.markets.getProcessedOrderbook(conditionId);
+    }
+    /**
+     * Detect arbitrage opportunity
+     *
+     * 使用有效价格计算套利机会（正确考虑镜像订单）
+     * 详细文档见: docs/01-polymarket-orderbook-arbitrage.md
+     */
+    async detectArbitrage(conditionId, threshold = 0.005) {
+        const orderbook = await this.getOrderbook(conditionId);
+        const { effectivePrices, longArbProfit, shortArbProfit } = orderbook.summary;
+        if (longArbProfit > threshold) {
+            return {
+                type: 'long',
+                profit: longArbProfit,
+                action: `Buy YES @ ${effectivePrices.effectiveBuyYes.toFixed(4)} + Buy NO @ ${effectivePrices.effectiveBuyNo.toFixed(4)}, merge for 1 USDC`,
+                expectedProfit: longArbProfit,
+            };
+        }
+        if (shortArbProfit > threshold) {
+            return {
+                type: 'short',
+                profit: shortArbProfit,
+                action: `Split 1 USDC, Sell YES @ ${effectivePrices.effectiveSellYes.toFixed(4)} + Sell NO @ ${effectivePrices.effectiveSellNo.toFixed(4)}`,
+                expectedProfit: shortArbProfit,
+            };
+        }
+        return null;
+    }
+    // ===== Cache Management =====
+    /**
+     * Clear all cached data
+     */
+    clearCache() {
+        this.cache.clear();
+    }
+    /**
+     * Invalidate cache for a specific market
+     */
+    invalidateMarketCache(conditionId) {
+        this.cache.invalidate(conditionId);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

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

package/dist/src/services/arbitrage-service.d.ts

@@ -0,0 +1,409 @@
+/**
+ * ArbitrageService - Real-time Arbitrage Detection and Execution
+ *
+ * Uses WebSocket for real-time orderbook monitoring and automatically
+ * detects arbitrage opportunities in Polymarket binary markets.
+ *
+ * Strategy:
+ * - Long Arb: Buy YES + NO (effective cost < $1) → Merge → $1 USDC
+ * - Short Arb: Sell pre-held YES + NO tokens (effective revenue > $1)
+ *
+ * Features:
+ * - Real-time orderbook monitoring via WebSocket
+ * - Automatic arbitrage detection using effective prices
+ * - Configurable profit threshold and trade sizes
+ * - Auto-execute mode or event-based manual mode
+ * - Balance tracking and position management
+ *
+ * Based on: scripts/arb/faze-bo3-arb.ts
+ * Docs: docs/arbitrage.md
+ */
+import { EventEmitter } from 'events';
+export interface ArbitrageMarketConfig {
+    /** Market name for logging */
+    name: string;
+    /** Condition ID */
+    conditionId: string;
+    /** YES token ID from CLOB API */
+    yesTokenId: string;
+    /** NO token ID from CLOB API */
+    noTokenId: string;
+    /** Outcome names [YES, NO] */
+    outcomes?: [string, string];
+}
+export interface ArbitrageServiceConfig {
+    /** Private key for trading (optional for monitor-only mode) */
+    privateKey?: string;
+    /** RPC URL for CTF operations */
+    rpcUrl?: string;
+    /** Minimum profit threshold (default: 0.005 = 0.5%) */
+    profitThreshold?: number;
+    /** Minimum trade size in USDC (default: 5) */
+    minTradeSize?: number;
+    /** Maximum single trade size in USDC (default: 100) */
+    maxTradeSize?: number;
+    /** Minimum token reserve for short arb (default: 10) */
+    minTokenReserve?: number;
+    /** Auto-execute mode (default: false) */
+    autoExecute?: boolean;
+    /** Enable logging (default: true) */
+    enableLogging?: boolean;
+    /** Cooldown between executions in ms (default: 5000) */
+    executionCooldown?: number;
+    /** Enable auto-rebalancing (default: false) */
+    enableRebalancer?: boolean;
+    /** Minimum USDC ratio 0-1 (default: 0.2 = 20%) - Split if below */
+    minUsdcRatio?: number;
+    /** Maximum USDC ratio 0-1 (default: 0.8 = 80%) - Merge if above */
+    maxUsdcRatio?: number;
+    /** Target USDC ratio when rebalancing (default: 0.5 = 50%) */
+    targetUsdcRatio?: number;
+    /** Max YES/NO imbalance before auto-fix (default: 5 tokens) */
+    imbalanceThreshold?: number;
+    /** Rebalance check interval in ms (default: 10000) */
+    rebalanceInterval?: number;
+    /** Minimum cooldown between rebalance actions in ms (default: 30000) */
+    rebalanceCooldown?: number;
+    /** Size safety factor 0-1 (default: 0.8) - use only 80% of orderbook depth to prevent partial fills */
+    sizeSafetyFactor?: number;
+    /** Auto-fix imbalance after failed execution (default: true) */
+    autoFixImbalance?: boolean;
+}
+export interface RebalanceAction {
+    type: 'split' | 'merge' | 'sell_yes' | 'sell_no' | 'none';
+    amount: number;
+    reason: string;
+    priority: number;
+}
+export interface RebalanceResult {
+    success: boolean;
+    action: RebalanceAction;
+    txHash?: string;
+    error?: string;
+}
+export interface SettleResult {
+    market: ArbitrageMarketConfig;
+    yesBalance: number;
+    noBalance: number;
+    pairedTokens: number;
+    unpairedYes: number;
+    unpairedNo: number;
+    merged: boolean;
+    mergeAmount?: number;
+    mergeTxHash?: string;
+    usdcRecovered?: number;
+    error?: string;
+}
+export interface ClearPositionResult {
+    market: ArbitrageMarketConfig;
+    marketStatus: 'active' | 'resolved' | 'unknown';
+    yesBalance: number;
+    noBalance: number;
+    actions: ClearAction[];
+    totalUsdcRecovered: number;
+    success: boolean;
+    error?: string;
+}
+export interface ClearAction {
+    type: 'merge' | 'sell_yes' | 'sell_no' | 'redeem';
+    amount: number;
+    usdcResult: number;
+    txHash?: string;
+    success: boolean;
+    error?: string;
+}
+export interface ScanCriteria {
+    /** Minimum 24h volume in USDC (default: 1000) */
+    minVolume24h?: number;
+    /** Maximum 24h volume (optional) */
+    maxVolume24h?: number;
+    /** Keywords to filter markets (optional) */
+    keywords?: string[];
+    /** Maximum number of markets to scan (default: 100) */
+    limit?: number;
+}
+export interface ScanResult {
+    /** Market config ready to use with start() */
+    market: ArbitrageMarketConfig;
+    /** Best arbitrage type */
+    arbType: 'long' | 'short' | 'none';
+    /** Profit rate (e.g., 0.01 = 1%) */
+    profitRate: number;
+    /** Profit percentage */
+    profitPercent: number;
+    /** Effective prices */
+    effectivePrices: {
+        buyYes: number;
+        buyNo: number;
+        sellYes: number;
+        sellNo: number;
+        longCost: number;
+        shortRevenue: number;
+    };
+    /** 24h volume */
+    volume24h: number;
+    /** Available size on orderbook */
+    availableSize: number;
+    /** Score 0-100 */
+    score: number;
+    /** Description */
+    description: string;
+}
+export interface OrderbookState {
+    yesBids: Array<{
+        price: number;
+        size: number;
+    }>;
+    yesAsks: Array<{
+        price: number;
+        size: number;
+    }>;
+    noBids: Array<{
+        price: number;
+        size: number;
+    }>;
+    noAsks: Array<{
+        price: number;
+        size: number;
+    }>;
+    lastUpdate: number;
+}
+export interface BalanceState {
+    usdc: number;
+    yesTokens: number;
+    noTokens: number;
+    lastUpdate: number;
+}
+export interface ArbitrageOpportunity {
+    type: 'long' | 'short';
+    /** Profit rate (0.01 = 1%) */
+    profitRate: number;
+    /** Profit in percentage */
+    profitPercent: number;
+    /** Effective buy/sell prices */
+    effectivePrices: {
+        buyYes: number;
+        buyNo: number;
+        sellYes: number;
+        sellNo: number;
+    };
+    /** Maximum executable size based on orderbook depth */
+    maxOrderbookSize: number;
+    /** Maximum executable size based on balance */
+    maxBalanceSize: number;
+    /** Recommended trade size */
+    recommendedSize: number;
+    /** Estimated profit in USDC */
+    estimatedProfit: number;
+    /** Description */
+    description: string;
+    /** Timestamp */
+    timestamp: number;
+}
+export interface ArbitrageExecutionResult {
+    success: boolean;
+    type: 'long' | 'short';
+    size: number;
+    profit: number;
+    txHashes: string[];
+    error?: string;
+    executionTimeMs: number;
+}
+export interface ArbitrageServiceEvents {
+    opportunity: (opportunity: ArbitrageOpportunity) => void;
+    execution: (result: ArbitrageExecutionResult) => void;
+    balanceUpdate: (balance: BalanceState) => void;
+    orderbookUpdate: (orderbook: OrderbookState) => void;
+    rebalance: (result: RebalanceResult) => void;
+    settle: (result: SettleResult) => void;
+    error: (error: Error) => void;
+    started: (market: ArbitrageMarketConfig) => void;
+    stopped: () => void;
+}
+export declare class ArbitrageService extends EventEmitter {
+    private realtimeService;
+    private marketSubscription;
+    private ctf;
+    private tradingService;
+    private rateLimiter;
+    private market;
+    private config;
+    private orderbook;
+    private balance;
+    private isExecuting;
+    private lastExecutionTime;
+    private lastRebalanceTime;
+    private balanceUpdateInterval;
+    private rebalanceInterval;
+    private isRunning;
+    private totalCapital;
+    private stats;
+    constructor(config?: ArbitrageServiceConfig);
+    /**
+     * Start monitoring a market for arbitrage opportunities
+     */
+    start(market: ArbitrageMarketConfig): Promise<void>;
+    /**
+     * Stop monitoring
+     */
+    stop(): Promise<void>;
+    /**
+     * Get current orderbook state
+     */
+    getOrderbook(): OrderbookState;
+    /**
+     * Get current balance state
+     */
+    getBalance(): BalanceState;
+    /**
+     * Get statistics
+     */
+    getStats(): {
+        runningTimeMs: number;
+        opportunitiesDetected: number;
+        executionsAttempted: number;
+        executionsSucceeded: number;
+        totalProfit: number;
+        startTime: number;
+    };
+    /**
+     * Check for arbitrage opportunity based on current orderbook
+     */
+    checkOpportunity(): ArbitrageOpportunity | null;
+    /**
+     * Manually execute an arbitrage opportunity
+     */
+    execute(opportunity: ArbitrageOpportunity): Promise<ArbitrageExecutionResult>;
+    /**
+     * Calculate recommended rebalance action based on current state
+     */
+    calculateRebalanceAction(): RebalanceAction;
+    /**
+     * Execute a rebalance action
+     */
+    rebalance(action?: RebalanceAction): Promise<RebalanceResult>;
+    /**
+     * Settle a market position - merge paired tokens to recover USDC
+     * @param market Market to settle (defaults to current market)
+     * @param execute If true, execute the merge. If false, just return info.
+     */
+    settlePosition(market?: ArbitrageMarketConfig, execute?: boolean): Promise<SettleResult>;
+    /**
+     * Settle multiple markets at once
+     */
+    settleMultiple(markets: ArbitrageMarketConfig[], execute?: boolean): Promise<SettleResult[]>;
+    /**
+     * Clear all positions in a market using the best strategy
+     *
+     * Strategy:
+     * - Active market: Merge paired tokens → Sell remaining unpaired tokens
+     * - Resolved market: Redeem winning tokens
+     *
+     * @param market Market to clear positions from
+     * @param execute If true, execute the clearing. If false, just return info.
+     * @returns Result with all actions taken
+     *
+     * @example
+     * ```typescript
+     * const service = new ArbitrageService({ privateKey: '0x...' });
+     *
+     * // View clearing plan
+     * const plan = await service.clearPositions(market, false);
+     * console.log(`Will recover: $${plan.totalUsdcRecovered}`);
+     *
+     * // Execute clearing
+     * const result = await service.clearPositions(market, true);
+     * ```
+     */
+    clearPositions(market: ArbitrageMarketConfig, execute?: boolean): Promise<ClearPositionResult>;
+    /**
+     * Clear positions from multiple markets
+     *
+     * @param markets Markets to clear
+     * @param execute If true, execute clearing
+     * @returns Results for all markets
+     */
+    clearAllPositions(markets: ArbitrageMarketConfig[], execute?: boolean): Promise<ClearPositionResult[]>;
+    private handleBookUpdate;
+    private checkAndHandleOpportunity;
+    private checkAndRebalance;
+    /**
+     * Fix YES/NO imbalance immediately after partial execution
+     * This is critical when one side of a parallel order fails
+     */
+    private fixImbalanceIfNeeded;
+    private updateBalance;
+    private executeLongArb;
+    private executeShortArb;
+    private log;
+    /**
+     * Scan markets for arbitrage opportunities
+     *
+     * @param criteria Filter criteria for markets
+     * @param minProfit Minimum profit threshold (default: 0.005 = 0.5%)
+     * @returns Array of scan results sorted by profit
+     *
+     * @example
+     * ```typescript
+     * const service = new ArbitrageService({ privateKey: '0x...' });
+     *
+     * // Scan markets with at least $5000 volume
+     * const results = await service.scanMarkets({ minVolume24h: 5000 }, 0.005);
+     *
+     * // Start arbitraging the best opportunity
+     * if (results.length > 0 && results[0].arbType !== 'none') {
+     *   await service.start(results[0].market);
+     * }
+     * ```
+     */
+    scanMarkets(criteria?: ScanCriteria, minProfit?: number): Promise<ScanResult[]>;
+    /**
+     * Quick scan for best arbitrage opportunities
+     *
+     * @param minProfit Minimum profit threshold (default: 0.005 = 0.5%)
+     * @param limit Maximum number of results to return (default: 10)
+     * @returns Top arbitrage opportunities
+     *
+     * @example
+     * ```typescript
+     * const service = new ArbitrageService({ privateKey: '0x...' });
+     *
+     * // Find best arbitrage opportunities
+     * const top = await service.quickScan(0.005, 5);
+     *
+     * // Print results
+     * for (const r of top) {
+     *   console.log(`${r.market.name}: ${r.arbType} +${r.profitPercent.toFixed(2)}%`);
+     * }
+     *
+     * // Start the best one
+     * if (top.length > 0) {
+     *   await service.start(top[0].market);
+     * }
+     * ```
+     */
+    quickScan(minProfit?: number, limit?: number): Promise<ScanResult[]>;
+    /**
+     * Find and start arbitraging the best opportunity
+     *
+     * @param minProfit Minimum profit threshold (default: 0.005 = 0.5%)
+     * @returns The scan result that was started, or null if none found
+     *
+     * @example
+     * ```typescript
+     * const service = new ArbitrageService({
+     *   privateKey: '0x...',
+     *   autoExecute: true,
+     *   profitThreshold: 0.005,
+     * });
+     *
+     * // Find and start the best opportunity
+     * const started = await service.findAndStart(0.005);
+     * if (started) {
+     *   console.log(`Started: ${started.market.name} (+${started.profitPercent.toFixed(2)}%)`);
+     * }
+     * ```
+     */
+    findAndStart(minProfit?: number): Promise<ScanResult | null>;
+}
+//# sourceMappingURL=arbitrage-service.d.ts.map