--- name: opportunity description: "Find and execute cross-platform arbitrage opportunities across prediction markets" emoji: "🎯" gates: envs: anyOf: - POLY_API_KEY - KALSHI_API_KEY --- # Opportunity Finder - Complete API Reference Discover and execute cross-platform arbitrage opportunities across Polymarket, Kalshi, Betfair, Smarkets, Manifold, Metaculus, PredictIt, and Drift. Based on [arXiv:2508.03474](https:\/\/arxiv.org\/abs\/2508.03474) which found **$40M+ in realized arbitrage** on Polymarket. ## Opportunity Types | Type | Description | Example | |------|-------------|---------| | **Internal** | YES + NO < $1 on same platform | Buy both for guaranteed profit | | **Cross-Platform** | Same market priced differently | Buy low on A, sell high on B | | **Combinatorial** | Logical violations (P(A) > P(B) when A implies B) | Trump > Republican | | **Edge** | Market vs external model (538, polls) | Market 45%, model 52% | --- ## Chat Commands ### Scanning ``` \/opportunities scan # Scan all platforms for opportunities \/opportunities scan "trump" # Scan with keyword filter \/opportunities scan --min-edge 2 # Min 2% edge \/opportunities scan --min-liquidity 1000 # Min $1000 liquidity \/opportunities active # View active opportunities \/opportunities active --sort edge # Sort by edge size \/opportunities active --sort liquidity # Sort by liquidity ``` ### Real-Time Monitoring ``` \/opportunities realtime start # Start continuous scanning \/opportunities realtime stop # Stop scanning \/opportunities realtime status # Check monitoring status \/opportunities realtime config --interval 30 # Set scan interval (seconds) ``` ### Market Linking ``` \/opportunities link

# Manually link equivalent markets \/opportunities unlink

# Remove link \/opportunities links # View all linked markets \/opportunities auto-match # Run auto-matching algorithm ``` ### Execution ``` \/opportunities execute # Execute an opportunity \/opportunities execute --size 100 # Execute with $100 size \/opportunities mark-taken # Mark as taken (manual) \/opportunities record-outcome # Record P&L outcome ``` ### Analytics ``` \/opportunities stats # Performance statistics \/opportunities stats --period 7d # Last 7 days \/opportunities history # Past opportunities \/opportunities by-platform # Stats by platform pair \/opportunities by-type # Stats by opportunity type ``` ### Risk Modeling ``` \/opportunities risk # Model execution risk \/opportunities estimate # Estimate execution costs \/opportunities kelly # Calculate Kelly fraction ``` --- ## TypeScript API Reference ### Create Opportunity Finder ```typescript import { createOpportunityFinder } from 'clodds\/opportunity'; const finder = createOpportunityFinder({ platforms: ['polymarket', 'kalshi', 'betfair', 'manifold'], \/\/ Filtering minEdge: 0.5, \/\/ 0.5% minimum edge minLiquidity: 500, \/\/ $500 minimum liquidity minConfidence: 0.7, \/\/ 70% match confidence \/\/ Real-time enableRealtime: true, scanIntervalMs: 30000, \/\/ 30 second intervals \/\/ Credentials polymarket: { apiKey, apiSecret, passphrase, privateKey }, kalshi: { apiKey, privateKey }, }); ``` ### Scan for Opportunities ```typescript \/\/ One-time scan const opportunities = await finder.scan({ query: 'election', \/\/ Optional keyword minEdge: 1, \/\/ 1% minimum minLiquidity: 1000, \/\/ $1000 minimum platforms: ['polymarket', 'kalshi'], }); for (const opp of opportunities) { console.log(`${opp.type}: ${opp.description}`); console.log(` Edge: ${opp.edge.toFixed(2)}%`); console.log(` Liquidity: $${opp.liquidity.toLocaleString()}`); console.log(` Confidence: ${(opp.confidence * 100).toFixed(0)}%`); console.log(` Score: ${opp.score}\/100`); console.log(` Platforms: ${opp.platforms.join(' ↔ ')}`); } ``` ### Real-Time Monitoring ```typescript \/\/ Start real-time scanning await finder.startRealtime(); \/\/ Event handlers finder.on('opportunity', (opp) => { console.log(`🎯 New opportunity: ${opp.description}`); console.log(` Edge: ${opp.edge.toFixed(2)}%`); }); finder.on('opportunityExpired', (opp) => { console.log(`❌ Opportunity expired: ${opp.id}`); }); finder.on('opportunityUpdated', (opp) => { console.log(`📊 Updated: ${opp.id} - Edge now ${opp.edge.toFixed(2)}%`); }); \/\/ Get active opportunities const active = await finder.getActive(); \/\/ Stop monitoring await finder.stopRealtime(); ``` ### Market Linking ```typescript \/\/ Manually link equivalent markets await finder.linkMarkets( { platform: 'polymarket', id: 'market-123' }, { platform: 'kalshi', id: 'TRUMP-WIN' } ); \/\/ Auto-match using semantic similarity const matches = await finder.autoMatchMarkets({ minSimilarity: 0.85, platforms: ['polymarket', 'kalshi'], }); console.log(`Found ${matches.length} potential matches`); for (const match of matches) { console.log(`${match.marketA.question}`); console.log(` ↔ ${match.marketB.question}`); console.log(` Similarity: ${(match.similarity * 100).toFixed(0)}%`); } \/\/ Get all links const links = await finder.getLinks(); ``` ### Execute Opportunity ```typescript \/\/ Execute an opportunity const result = await finder.execute(opportunityId, { size: 100, \/\/ $100 position maxSlippage: 0.5, \/\/ 0.5% max slippage useProtectedOrders: true, }); console.log(`Executed: ${result.status}`); console.log(` Filled: $${result.filledSize}`); console.log(` Avg price: ${result.avgPrice}`); console.log(` Fees: $${result.fees}`); \/\/ Mark as taken manually await finder.markTaken(opportunityId); \/\/ Record outcome await finder.recordOutcome(opportunityId, { pnl: 25.50, exitPrice: 0.55, exitTimestamp: Date.now(), }); ``` ### Analytics ```typescript \/\/ Get statistics const stats = await finder.getAnalytics({ period: '30d', }); console.log(`Total opportunities: ${stats.total}`); console.log(`Taken: ${stats.taken}`); console.log(`Win rate: ${(stats.winRate * 100).toFixed(1)}%`); console.log(`Total P&L: $${stats.totalPnl.toLocaleString()}`); console.log(`Avg edge: ${stats.avgEdge.toFixed(2)}%`); console.log(`By platform pair:`); for (const [pair, data] of Object.entries(stats.byPlatformPair)) { console.log(` ${pair}: ${data.count} opps, $${data.pnl} P&L`); } ``` ### Risk Modeling ```typescript \/\/ Model execution risk const risk = await finder.modelRisk(opportunityId); console.log(`Execution risk:`); console.log(` Fill probability: ${(risk.fillProbability * 100).toFixed(0)}%`); console.log(` Expected slippage: ${risk.expectedSlippage.toFixed(2)}%`); console.log(` Time to fill: ${risk.estimatedTimeToFill}s`); console.log(` Counterparty risk: ${risk.counterpartyRisk}`); \/\/ Estimate execution const estimate = await finder.estimateExecution(opportunityId, { size: 500, }); console.log(`Execution estimate for $500:`); console.log(` Expected fill: $${estimate.expectedFill}`); console.log(` Expected cost: $${estimate.expectedCost}`); console.log(` Net edge after costs: ${estimate.netEdge.toFixed(2)}%`); ``` --- ## Opportunity Scoring Opportunities are scored 0-100 based on: | Factor | Weight | Description | |--------|--------|-------------| | Edge % | 35% | Raw arbitrage spread | | Liquidity | 25% | Available volume | | Confidence | 25% | Match quality | | Execution | 15% | Platform reliability | ### Penalties - Low liquidity (<$1000): -5 points - Cross-platform complexity: -3 per platform - High slippage (>2%): -5 points - Low confidence (<70%): -5 points - Near expiry (<24h): -3 points --- ## Semantic Matching Markets are matched using: 1. **Exact slug match** - Platform-specific IDs 2. **Text similarity** - Jaccard coefficient 3. **Vector embeddings** - Semantic similarity 4. **Manual links** - User-defined ```typescript \/\/ Configure matching finder.setMatchingConfig({ minTextSimilarity: 0.8, minEmbeddingSimilarity: 0.85, useManualLinksFirst: true, }); ``` --- ## Best Practices 1. **Start with high-confidence matches** - 85%+ similarity 2. **Check liquidity** - Ensure enough volume to execute 3. **Account for fees** - Factor in platform fees 4. **Use protected orders** - Avoid slippage 5. **Monitor in real-time** - Opportunities disappear fast 6. **Track outcomes** - Build performance history