Opportunity

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 which found $40M+ in realized arbitrage on Polymarket.

Opportunity Types

Chat Commands

Scanning

Copy code
/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

Copy code
/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

Copy code
/opportunities link <market-a> <market-b>   # Manually link equivalent markets
/opportunities unlink <market-a> <market-b> # Remove link
/opportunities links                        # View all linked markets
/opportunities auto-match                   # Run auto-matching algorithm

Execution

Copy code
/opportunities execute <id>                 # Execute an opportunity
/opportunities execute <id> --size 100      # Execute with $100 size
/opportunities mark-taken <id>              # Mark as taken (manual)
/opportunities record-outcome <id> <pnl>    # Record P&L outcome

Analytics

Copy code
/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

Copy code
/opportunities risk <id>                    # Model execution risk
/opportunities estimate <id>                # Estimate execution costs
/opportunities kelly <id>                   # Calculate Kelly fraction

TypeScript API Reference

Create Opportunity Finder

typescriptCopy code
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

typescriptCopy code
// 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

typescriptCopy code
// 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

typescriptCopy code
// 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

typescriptCopy code
// 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

typescriptCopy code
// 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

typescriptCopy code
// 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:

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

typescriptCopy code
// 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