Polymarket Arbitrage Scanner - Technical Specification

This video demonstrates how a specification is generated using HeadGym Pablo. From loose instructions, Pablo creates and executes a plan, correctly identifying where the specification needs to be written. It then proceeds to create the artifact after confirming user approval. The resulting document is also show below.

1. Overview

A Python application that scans Polymarket for markets resolving within 15 minutes, analyzes order books for YES/NO outcomes, and identifies profitable arbitrage opportunities after accounting for gas fees.

Purpose

Identify and alert on arbitrage opportunities in Polymarket prediction markets where the combined cost of buying both YES and NO outcome tokens is less than $1.00, accounting for transaction costs.

Key Concept

In prediction markets, YES + NO tokens for the same market should equal $1.00 at resolution. If the combined cost is less than $1.00 before resolution, there’s an arbitrage opportunity to profit from the difference, minus gas fees.

2. Core Functionality

2.1 Market Discovery

Objective: Identify all markets resolving within the next 15 minutes

Data Required:

Market end time/resolution time
Market ID and metadata
Current market status (active/closed)
Market question/description

API Integration:

Use Polymarket API to fetch active markets
Filter by resolution time window (≤ 15 minutes)
Refresh market list periodically

Key Considerations:

Markets may resolve early
Need to account for timezone differences
Handle markets with uncertain resolution times

2.2 Order Book Analysis

For each qualifying market:

Fetch Order Books:

Retrieve current open orders for both YES and NO outcomes
Use CLOB (Central Limit Order Book) API

Identify Best Prices:

Best YES ask (cheapest YES tokens available to buy)
Best NO ask (cheapest NO tokens available to buy)
Verify sufficient liquidity at these price points

Calculate Combined Cost:

Sum of best YES ask + best NO ask
Account for order size and available liquidity

Data Validation:

Ensure order book data is current (timestamp check)
Verify order sizes meet minimum thresholds
Handle missing or incomplete order book data

2.3 Arbitrage Detection

Arbitrage Condition: Combined cost < $1.00

Theoretical Profit Calculation:


Theoretical Profit = $1.00 - (YES ask + NO ask)

Gas Fee Estimation:

Query current Polygon network gas prices
Estimate gas costs for buying YES tokens (contract interaction)
Estimate gas costs for buying NO tokens (contract interaction)
Apply safety buffer (e.g., 20%) for gas price volatility
Total transaction costs = Gas for YES + Gas for NO

Net Profit Calculation:


Net Profit = Theoretical Profit - Total Gas Fees

Additional Costs to Consider:

Platform fees (if any)
Slippage tolerance
Price impact of trade size

2.4 Profitability Threshold

Filtering Criteria:

Only flag opportunities where: Net Profit > 0
Apply minimum profit threshold (e.g., $5-10) to make execution worthwhile
Consider profit as percentage of investment

Risk-Adjusted Profitability:

Factor in time until resolution
Consider market volatility
Account for execution risk

3. Technical Architecture

3.1 Data Sources

Polymarket API:

Market metadata and details
Resolution times
Market status

CLOB (Central Limit Order Book):

Real-time order book data
Best bid/ask prices
Order depth and liquidity

Polygon Network:

Current gas prices (gwei)
Network congestion metrics
Transaction cost estimation

3.2 Key Components

Module 1: Market Scanner

Responsibilities:

Poll Polymarket API for active markets
Filter by resolution time (< 15 minutes)
Cache market data to avoid redundant API calls
Handle API rate limits

Implementation Details:

Configurable polling interval (default: 30 seconds)
Exponential backoff for API failures
Market deduplication logic

Module 2: Order Book Analyzer

Responsibilities:

Fetch order book for each qualifying market
Parse YES/NO order books
Extract best ask prices
Validate order liquidity (ensure sufficient volume)

Implementation Details:

Separate API calls for YES and NO tokens
Parse order book response format
Handle missing or malformed data
Calculate weighted average prices if needed

Module 3: Gas Fee Calculator

Responsibilities:

Query current Polygon gas prices
Estimate transaction costs based on:
- Contract interaction complexity
- Current network congestion
- Priority fee requirements

Implementation Details:

Use Web3 library to query gas prices
Estimate gas units for typical transactions
Apply configurable safety buffer
Cache gas prices with short TTL

Module 4: Arbitrage Evaluator

Responsibilities:

Calculate theoretical profit
Subtract gas costs
Apply profit threshold filter
Rank opportunities by profitability

Implementation Details:

Combine data from all previous modules
Apply business logic for opportunity detection
Calculate risk-adjusted scores
Sort opportunities by net profit

Module 5: Alert/Notification System

Responsibilities:

Log opportunities to console/file
Optional: Send alerts (webhook, email, Discord, etc.)
Display key metrics (profit, market details, timing)
Maintain alert history

Implementation Details:

Structured logging (JSON format)
Configurable alert channels
Rate limiting to avoid spam
Alert deduplication

3.3 Data Models

Market Object


{
    "market_id": str,              # Unique market identifier
    "condition_id": str,           # Condition ID for the market
    "question": str,               # Market question text
    "end_time": datetime,          # Scheduled resolution time
    "end_time_iso": str,           # ISO format timestamp
    "minutes_until_resolution": int, # Time remaining
    "yes_token_id": str,           # YES outcome token ID
    "no_token_id": str,            # NO outcome token ID
    "yes_ask": float,              # Best YES ask price
    "no_ask": float,               # Best NO ask price
    "yes_liquidity": float,        # Available YES volume at ask
    "no_liquidity": float,         # Available NO volume at ask
    "combined_cost": float,        # yes_ask + no_ask
    "theoretical_profit": float,   # 1.00 - combined_cost
    "estimated_gas_fees": float,   # Total gas costs
    "net_profit": float,           # theoretical_profit - gas_fees
    "profit_percentage": float,    # net_profit / combined_cost
    "status": str,                 # Market status (active, closed, etc.)
    "tags": list,                  # Market categories/tags
    "volume": float,               # Total market volume
    "liquidity": float             # Total market liquidity
}

Arbitrage Opportunity


{
    "opportunity_id": str,         # Unique opportunity identifier
    "timestamp": datetime,         # When opportunity was detected
    "market": Market,              # Full market object
    "profit_potential": float,     # Net profit in dollars
    "profit_percentage": float,    # ROI percentage
    "confidence_score": float,     # 0-1 confidence rating
    "risk_level": str,             # LOW, MEDIUM, HIGH
    "recommended_action": str,     # EXECUTE, MONITOR, SKIP
    "execution_window": int,       # Seconds until resolution
    "gas_price_gwei": float,       # Current gas price
    "alert_sent": bool,            # Whether alert was sent
    "notes": str                   # Additional context
}

Order Book Entry


{
    "price": float,                # Price per token
    "size": float,                 # Number of tokens available
    "timestamp": datetime,         # Order timestamp
    "maker": str                   # Order maker address (optional)
}

Gas Estimate


{
    "base_fee": float,             # Base fee in gwei
    "priority_fee": float,         # Priority fee in gwei
    "total_gwei": float,           # Total gas price
    "estimated_units": int,        # Estimated gas units
    "estimated_cost_usd": float,   # Cost in USD
    "buffer_percentage": float,    # Safety buffer applied
    "timestamp": datetime          # When estimate was made
}

4. Configuration Parameters

4.1 Scanning Configuration


SCAN_INTERVAL = 30                # Seconds between scans
RESOLUTION_WINDOW = 15            # Minutes before resolution to consider
MAX_MARKETS_PER_SCAN = 100        # Limit markets processed per scan
API_TIMEOUT = 10                  # API request timeout in seconds
MAX_RETRIES = 3                   # Max API retry attempts

4.2 Profitability Thresholds


MIN_PROFIT_THRESHOLD = 5.0        # Minimum net profit in USD
MIN_PROFIT_PERCENTAGE = 2.0       # Minimum ROI percentage
MIN_LIQUIDITY = 100.0             # Minimum order size in USD
MAX_COMBINED_COST = 0.98          # Max YES+NO cost for consideration

4.3 Gas Configuration


GAS_PRICE_BUFFER = 20             # Percentage buffer for gas estimates
MAX_GAS_PRICE_GWEI = 500          # Maximum acceptable gas price
GAS_ESTIMATE_CACHE_TTL = 30       # Cache gas estimates for N seconds
ESTIMATED_GAS_UNITS = 150000      # Estimated gas per transaction

4.4 Risk Management


MAX_SLIPPAGE = 2.0                # Maximum acceptable slippage %
MIN_TIME_TO_RESOLUTION = 5        # Minimum minutes before resolution
MAX_EXECUTION_TIME = 60           # Max seconds to execute trade
CONFIDENCE_THRESHOLD = 0.7        # Minimum confidence to alert

4.5 Alert Configuration


ENABLE_CONSOLE_ALERTS = True      # Print to console
ENABLE_FILE_LOGGING = True        # Log to file
ENABLE_WEBHOOK_ALERTS = False     # Send webhook notifications
WEBHOOK_URL = ""                  # Webhook endpoint
ALERT_RATE_LIMIT = 10             # Max alerts per minute
LOG_FILE_PATH = "logs/arbitrage.log"

5. Risk Considerations

5.1 Market Risks

Resolution Timing:

Markets might resolve earlier than expected
Resolution may be delayed or disputed
Mitigation: Only consider markets with clear, imminent resolution times

Price Movement:

Order book can change between analysis and execution
Prices may move against you during transaction
Mitigation: Fast execution, slippage protection

Market Manipulation:

Fake orders or wash trading
Sudden order cancellations
Mitigation: Validate order book depth, check market history

5.2 Technical Risks

Gas Price Volatility:

Network congestion can spike gas costs suddenly
Profitable opportunity can become unprofitable
Mitigation: Real-time gas monitoring, safety buffers

API Failures:

Polymarket API downtime
Rate limiting
Stale data
Mitigation: Error handling, retries, multiple data sources

Execution Risk:

Time lag between detection and execution
Transaction failures
Insufficient balance
Mitigation: Pre-funded wallet, transaction monitoring

5.3 Liquidity Risks

Order Book Depth:

Insufficient volume at quoted prices
Large orders cause price impact
Mitigation: Validate liquidity before flagging opportunity

Partial Fills:

Orders may only partially execute
Leaves unhedged position
Mitigation: All-or-nothing order types where possible

5.4 Smart Contract Risks

Contract Bugs:

Potential vulnerabilities in Polymarket contracts
Approval issues
Mitigation: Use audited contracts, test transactions

Token Approval:

Need to approve tokens before trading
Additional gas costs
Mitigation: Pre-approve tokens, account for approval gas

6. API Integration Details

6.1 Polymarket API Endpoints

Get Active Markets:


GET https
=======
### 6.1 Polymarket API Endpoints

**Get Active Markets**:

GET https://gamma-api.polymarket.com/markets Query Parameters:

active: true
closed: false
limit: 100
offset: 0



**Get Market Details**:

GET https://gamma-api.polymarket.com/markets/{condition_id}



**Get Order Book (CLOB)**:

GET https://clob.polymarket.com/book Query Parameters:

token_id: token_id
side: BUY or SELL



**Get Gas Prices (Polygon)**:

GET https://gasstation-mainnet.matic.network/v2



### 6.2 Response Formats

**Market Response**:
```json
{
  "condition_id": "0x123...",
  "question": "Will X happen?",
  "end_date_iso": "2024-01-01T12:00:00Z",
  "tokens": [
    {
      "token_id": "0xabc...",
      "outcome": "Yes",
      "price": "0.55"
    },
    {
      "token_id": "0xdef...",
      "outcome": "No",
      "price": "0.47"
    }
  ],
  "volume": "50000.00",
  "liquidity": "10000.00"
}

Order Book Response:


{
  "market": "0x123...",
  "asset_id": "0xabc...",
  "bids": [
    {
      "price": "0.55",
      "size": "100.00"
    }
  ],
  "asks": [
    {
      "price": "0.56",
      "size": "150.00"
    }
  ]
}

7. Output Format

7.1 Console Output

Scanning Status:


[2024-01-01 12:00:00] Starting scan...
[2024-01-01 12:00:01] Found 45 markets resolving within 15 minutes
[2024-01-01 12:00:02] Analyzing order books...

Opportunity Alert:


╔════════════════════════════════════════════════════════════════╗
║              ARBITRAGE OPPORTUNITY DETECTED                     ║
╠════════════════════════════════════════════════════════════════╣
║ Market ID: 0x123abc...                                         ║
║ Question: Will Bitcoin reach $50k by end of day?               ║
║ Resolution: 12 minutes 34 seconds                              ║
╠════════════════════════════════════════════════════════════════╣
║ YES Ask:  $0.4500  (Liquidity: $250.00)                       ║
║ NO Ask:   $0.4800  (Liquidity: $300.00)                       ║
║ Combined: $0.9300                                              ║
╠════════════════════════════════════════════════════════════════╣
║ Theoretical Profit: $0.0700                                    ║
║ Gas Fees (Est):     $0.0150                                    ║
║ NET PROFIT:         $0.0550                                    ║
║ ROI:                5.91%                                      ║
╠════════════════════════════════════════════════════════════════╣
║ Status: ⚠️  MARGINAL (below $10 threshold)                     ║
║ Confidence: 75%                                                ║
║ Risk Level: MEDIUM                                             ║
║ Recommendation: MONITOR                                        ║
╚════════════════════════════════════════════════════════════════╝

No Opportunities:


[2024-01-01 12:00:05] No arbitrage opportunities found
[2024-01-01 12:00:05] Next scan in 30 seconds...

7.2 Log File Format (JSON)


{
  "timestamp": "2024-01-01T12:00:00Z",
  "scan_id": "scan_123",
  "markets_scanned": 45,
  "opportunities_found": 1,
  "opportunities": [
    {
      "opportunity_id": "opp_456",
      "market_id": "0x123abc",
      "question": "Will Bitcoin reach $50k by end of day?",
      "resolution_time": "2024-01-01T12:12:34Z",
      "minutes_until_resolution": 12.57,
      "yes_ask": 0.45,
      "no_ask": 0.48,
      "combined_cost": 0.93,
      "theoretical_profit": 0.07,
      "gas_fees": 0.015,
      "net_profit": 0.055,
      "profit_percentage": 5.91,
      "confidence_score": 0.75,
      "risk_level": "MEDIUM",
      "recommendation": "MONITOR",
      "gas_price_gwei": 35.5,
      "yes_liquidity": 250.0,
      "no_liquidity": 300.0
    }
  ],
  "scan_duration_ms": 2341,
  "errors": []
}

7.3 Webhook Payload


{
  "event": "arbitrage_opportunity",
  "timestamp": "2024-01-01T12:00:00Z",
  "opportunity": {
    "market_question": "Will Bitcoin reach $50k by end of day?",
    "net_profit": 0.055,
    "profit_percentage": 5.91,
    "time_remaining": "12m 34s",
    "recommendation": "MONITOR",
    "details_url": "https://polymarket.com/market/0x123abc"
  }
}

8. Error Handling

8.1 API Errors

Rate Limiting:

Implement exponential backoff
Queue requests to stay within limits
Cache responses when appropriate

Network Errors:

Retry failed requests (max 3 attempts)
Fallback to cached data if available
Log all failures for debugging

Invalid Responses:

Validate response schema
Handle missing fields gracefully
Skip malformed data with warning

8.2 Data Validation

Market Data:

Verify resolution time is in future
Check for required fields
Validate price ranges (0-1)

Order Book Data:

Ensure asks are present
Verify liquidity > minimum threshold
Check for stale timestamps

Gas Estimates:

Reject unreasonably high gas prices
Validate gas estimate is current
Use fallback values if API fails

8.3 Logging Strategy

Log Levels:

ERROR: API failures, validation errors, critical issues
WARNING: Missing data, rate limits, below-threshold opportunities
INFO: Scan results, opportunities found, execution attempts
DEBUG: Detailed API responses, calculation steps

Log Rotation:

Rotate daily or at 100MB
Keep last 30 days of logs
Compress old logs

9. Performance Optimization

9.1 Caching Strategy

Market Data:

Cache market list for 30 seconds
Cache individual market details for 60 seconds
Invalidate on explicit refresh

Gas Prices:

Cache for 30 seconds
Update on significant price changes (>10%)

Order Books:

No caching (must be real-time)
Fetch on-demand for each analysis

9.2 Parallel Processing

Concurrent Market Analysis:

Process multiple markets simultaneously
Use thread pool (10-20 workers)
Rate limit API calls across threads

Batch API Requests:

Combine requests where possible
Use bulk endpoints if available

9.3 Resource Management

Memory:

Limit market history retention
Clear old opportunities from memory
Stream large responses

Network:

Reuse HTTP connections
Implement connection pooling
Set appropriate timeouts

10. Security Considerations

10.1 API Key Management

Storage:

Store API keys in environment variables
Never commit keys to version control
Use secrets management service in production

Rotation:

Rotate keys periodically
Support multiple keys for failover

10.2 Webhook Security

Authentication:

Use signature verification for webhooks
Implement request signing
Validate webhook sources

Rate Limiting:

Limit webhook calls per minute
Implement backoff for failures

10.3 Data Privacy

Logging:

Avoid logging sensitive data
Redact wallet addresses in logs
Sanitize error messages

11. Testing Strategy

11.1 Unit Tests

Components to Test:

Market filtering logic
Profit calculation formulas
Gas fee estimation
Order book parsing
Data validation

Test Coverage:

Target 80%+ code coverage
Test edge cases and error conditions
Mock external API calls

11.2 Integration Tests

API Integration:

Test against live Polymarket API (rate-limited)
Verify response parsing
Handle API errors gracefully

End-to-End:

Full scan cycle with real data
Opportunity detection pipeline
Alert generation

11.3 Performance Tests

Load Testing:

Test with 100+ markets
Measure scan duration
Monitor memory usage

Stress Testing:

Test API rate limit handling
Simulate network failures
Test concurrent request handling

12. Deployment

12.1 Environment Setup

Requirements:


Python 3.9+
pip install -r requirements.txt

Dependencies:


requests>=2.28.0
web3>=6.0.0
python-dotenv>=0.19.0
pandas>=1.5.0

Environment Variables:


POLYMARKET_API_KEY=your_api_key
POLYGON_RPC_URL=https://polygon-rpc.com
WEBHOOK_URL=https://your-webhook.com/alerts
MIN_PROFIT_THRESHOLD=5.0
SCAN_INTERVAL=30

12.2 Running the Application

Development:


python arbitrage_scanner.py --dev

Production:


python arbitrage_scanner.py --config production.yaml

Docker:


docker build -t polymarket-scanner .
docker run -d --env-file .env polymarket-scanner

12.3 Monitoring

Health Checks:

Endpoint for service status
Last successful scan timestamp
Error rate metrics

Metrics to Track:

Scans per hour
Opportunities detected
Average scan duration
API error rate
Alert success rate

Alerting:

Alert on service downtime
Alert on high error rates
Alert on stale data

13. Future Enhancements

13.1 Auto-Execution (Phase 2)

Features:

Automatic trade execution for high-confidence opportunities
Wallet integration (MetaMask, WalletConnect)
Transaction monitoring and confirmation
Position tracking and management

Safety Mechanisms:

Maximum daily loss limits
Per-trade size limits
Manual approval for large trades
Kill switch for emergency stop

13.2 Advanced Analytics

Historical Tracking:

Database of past opportunities
Success rate analysis
Profit/loss tracking
Market behavior patterns

Machine Learning:

Predict optimal execution timing
Forecast gas price trends
Identify high-probability markets
Risk scoring models

13.3 Multi-Market Arbitrage

Cross-Market Opportunities:

Compare prices across different platforms
Bundle multiple small opportunities
Optimize for total profit

Portfolio Management:

Track multiple positions
Hedging strategies
Diversification across markets

13.4 Real-Time Features

WebSocket Integration:

Real-time order book updates
Instant price change notifications
Live market resolution alerts

Low-Latency Execution:

Direct blockchain integration
Optimized transaction routing
MEV protection strategies

13.5 User Interface

Web Dashboard:

Live opportunity feed
Historical performance charts
Market analysis tools
Configuration management

Mobile App:

Push notifications
Quick opportunity review
One-tap execution approval

14. Implementation Checklist

Phase 1: Core Scanner (MVP)

[ ] Set up project structure and dependencies
[ ] Implement Polymarket API client
[ ] Create market filtering by resolution time
[ ] Build order book parser
[ ] Implement gas fee estimation
[ ] Create arbitrage calculation logic
[ ] Add profit threshold filtering
[ ] Implement console logging
[ ] Add configuration management
[ ] Create main scanner loop
[ ] Add error handling and retries
[ ] Write unit tests
[ ] Create README documentation

Phase 2: Enhanced Features

[ ] Add file-based logging (JSON)
[ ] Implement webhook notifications
[ ] Add caching layer
[ ] Optimize with parallel processing
[ ] Create detailed analytics
[ ] Add performance monitoring
[ ] Implement health checks
[ ] Write integration tests
[ ] Create deployment scripts
[ ] Add Docker support

Phase 3: Advanced Features

[ ] Historical opportunity database
[ ] Advanced risk scoring
[ ] Multi-market comparison
[ ] Web dashboard UI
[ ] Auto-execution capability
[ ] Machine learning models
[ ] WebSocket real-time updates
[ ] Mobile notifications
[ ] Portfolio tracking

15. Code Structure

15.1 Project Directory Layout


polymarket-arbitrage-scanner/
├── src/
│   ├── __init__.py
│   ├── main.py                    # Entry point
│   ├── scanner.py                 # Main scanner logic
│   ├── api/
│   │   ├── __init__.py
│   │   ├── polymarket_client.py   # Polymarket API client
│   │   ├── clob_client.py         # Order book API client
│   │   └── gas_client.py          # Gas price API client
│   ├── models/
│   │   ├── __init__.py
│   │   ├── market.py              # Market data model
│   │   ├── opportunity.py         # Opportunity data model
│   │   └── order_book.py          # Order book data model
│   ├── analyzers/
│   │   ├── __init__.py
│   │   ├── market_analyzer.py     # Market filtering logic
│   │   ├── orderbook_analyzer.py  # Order book analysis
│   │   ├── gas_analyzer.py        # Gas fee calculation
│   │   └── arbitrage_analyzer.py  # Arbitrage detection
│   ├── utils/
│   │   ├── __init__.py
│   │   ├── logger.py              # Logging utilities
│   │   ├── config.py              # Configuration management
│   │   ├── cache.py               # Caching utilities
│   │   └── validators.py          # Data validation
│   └── alerts/
│       ├── __init__.py
│       ├── console_alert.py       # Console output
│       ├── file_alert.py          # File logging
│       └── webhook_alert.py       # Webhook notifications
├── tests/
│   ├── __init__.py
│   ├── test_scanner.py
│   ├── test_analyzers.py
│   ├── test_api_clients.py
│   └── test_models.py
├── config/
│   ├── config.yaml                # Default configuration
│   ├── production.yaml            # Production config
│   └── development.yaml           # Development config
├── logs/                          # Log files directory
├── .env.example                   # Environment variables template
├── .gitignore
├── requirements.txt               # Python dependencies
├── Dockerfile                     # Docker configuration
├── docker-compose.yml             # Docker compose setup
└── README.md                      # Project documentation

15.2 Key Classes

Scanner Class


class ArbitrageScanner:
    """Main scanner orchestrator"""
    
    def __init__(self, config):
        self.config = config
        self.market_client = PolymarketClient()
        self.clob_client = CLOBClient()
        self.gas_client = GasClient()
        self.analyzers = self._init_analyzers()
        
    def run(self):
        """Main scan loop"""
        pass
        
    def scan_markets(self):
        """Scan for opportunities"""
        pass
        
    def analyze_opportunity(self, market):
        """Analyze single market"""
        pass

Market Analyzer


class MarketAnalyzer:
    """Filters and validates markets"""
    
    def filter_by_resolution_time(self, markets, window_minutes):
        """Filter markets by resolution time"""
        pass
        
    def validate_market(self, market):
        """Validate market data"""
        pass

Arbitrage Analyzer


class ArbitrageAnalyzer:
    """Detects arbitrage opportunities"""
    
    def calculate_profit(self, yes_ask, no_ask, gas_fees):
        """Calculate net profit"""
        pass
        
    def evaluate_opportunity(self, market, order_book, gas_estimate):
        """Evaluate if opportunity is viable"""
        pass
        
    def calculate_confidence_score(self, opportunity):
        """Calculate confidence score"""
        pass

16. Sample Configuration File

config.yaml


# Polymarket Arbitrage Scanner Configuration
 
# Scanning Parameters
scanning:
  interval_seconds: 30
  resolution_window_minutes: 15
  max_markets_per_scan: 100
  
# API Configuration
api:
  polymarket:
    base_url: "https://gamma-api.polymarket.com"
    timeout_seconds: 10
    max_retries: 3
    retry_delay_seconds: 2
    
  clob:
    base_url: "https://clob.polymarket.com"
    timeout_seconds: 5
    
  gas:
    polygon_rpc: "${POLYGON_RPC_URL}"
    gasstation_url: "https://gasstation-mainnet.matic.network/v2"
    
# Profitability Thresholds
profitability:
  min_net_profit_usd: 5.0
  min_profit_percentage: 2.0
  min_liquidity_usd: 100.0
  max_combined_cost: 0.98
  
# Gas Configuration
gas:
  buffer_percentage: 20
  max_price_gwei: 500
  estimated_units_per_tx: 150000
  cache_ttl_seconds: 30
  
# Risk Management
risk:
  max_slippage_percentage: 2.0
  min_time_to_resolution_minutes: 5
  max_execution_time_seconds: 60
  confidence_threshold: 0.7
  
# Alerts
alerts:
  console:
    enabled: true
    format: "detailed"  # detailed, simple, json
    
  file:
    enabled: true
    path: "logs/arbitrage.log"
    format: "json"
    rotation: "daily"
    retention_days: 30
    
  webhook:
    enabled: false
    url: "${WEBHOOK_URL}"
    timeout_seconds: 5
    rate_limit_per_minute: 10
    retry_on_failure: true
    
# Performance
performance:
  enable_caching: true
  cache_ttl_seconds: 60
  parallel_workers: 10
  connection_pool_size: 20
  
# Logging
logging:
  level: "INFO"  # DEBUG, INFO, WARNING, ERROR
  format: "json"
  include_timestamps: true
  include_request_ids: true

17. Example Usage

17.1 Basic Usage


from src.scanner import ArbitrageScanner
from src.utils.config import load_config
 
# Load configuration
config = load_config("config/config.yaml")
 
# Initialize scanner
scanner = ArbitrageScanner(config)
 
# Run continuous scanning
scanner.run()

17.2 Single Scan


# Perform single scan
opportunities = scanner.scan_markets()
 
# Print results
for opp in opportunities:
    print(f"Market: {opp.market.question}")
    print(f"Net Profit: ${opp.profit_potential:.2f}")
    print(f"Time Remaining: {opp.execution_window}s")
    print("---")

17.3 Custom Configuration


# Override config parameters
config.profitability.min_net_profit_usd = 10.0
config.scanning.interval_seconds = 60
 
scanner = ArbitrageScanner(config)
scanner.run()

18. API Rate Limits & Best Practices

18.1 Polymarket API Limits

Rate Limits:

100 requests per minute (estimated)
Burst allowance: 10 requests
Reset window: 60 seconds

Best Practices:

Implement exponential backoff
Cache market data when possible
Use batch endpoints where available
Monitor rate limit headers

18.2 CLOB API Limits

Rate Limits:

200 requests per minute
Per-endpoint limits may vary

Best Practices:

Request only necessary order book depth
Use WebSocket for real-time updates (future)
Implement request queuing

18.3 Polygon RPC Limits

Public RPC Limits:

Varies by provider
Typically 100-1000 requests per day

Best Practices:

Use dedicated RPC endpoint
Cache gas prices
Batch RPC calls when possible

19. Troubleshooting Guide

19.1 Common Issues

No Markets Found:

Check if resolution_window is too narrow
Verify API connectivity
Check market status filters

High Gas Fees Eliminating Opportunities:

Adjust gas_buffer_percentage
Wait for lower network congestion
Consider minimum profit threshold

Stale Data:

Verify cache TTL settings
Check API response timestamps
Ensure system clock is synchronized

API Errors:

Check API key validity
Verify rate limits not exceeded
Review error logs for details

19.2 Debug Mode


# Enable debug logging
config.logging.level = "DEBUG"
 
# Run with verbose output
scanner = ArbitrageScanner(config)
scanner.run(verbose=True)

19.3 Health Checks


# Check scanner health
health = scanner.get_health_status()
 
print(f"Last Scan: {health['last_scan_time']}")
print(f"Markets Scanned: {health['total_markets_scanned']}")
print(f"Opportunities Found: {health['total_opportunities']}")
print(f"Error Rate: {health['error_rate']}%")

20. Glossary

Arbitrage: Simultaneous purchase and sale of assets to profit from price differences

CLOB: Central Limit Order Book - order matching system used by Polymarket

Condition ID: Unique identifier for a prediction market

Gas Fees: Transaction costs on Polygon blockchain

Liquidity: Available volume of tokens at a given price

Order Book: List of buy and sell orders for a market

Slippage: Difference between expected and actual execution price

Token ID: Unique identifier for YES or NO outcome tokens

YES/NO Tokens: Outcome tokens representing predictions

Resolution: When a market’s outcome is determined

Ask Price: Lowest price a seller is willing to accept

Bid Price: Highest price a buyer is willing to pay

Spread: Difference between bid and ask prices

ROI: Return on Investment - profit as percentage of capital

21. References & Resources

21.1 Documentation

Arbitrage in Prediction Markets (included in context)
Inside a Polymarket Bot (included in context)
Polymarket Strategy Article (included in context)

21.3 Tools & Libraries

requests: HTTP library for API calls
web3.py: Ethereum/Polygon blockchain interaction
pandas: Data analysis and manipulation
python-dotenv: Environment variable management
pyyaml: YAML configuration parsing

22. License & Disclaimer

22.1 Disclaimer

IMPORTANT: This software is for educational and research purposes only.

Risks:

Trading cryptocurrencies and prediction market tokens involves substantial risk
Past performance does not guarantee future results
You may lose all invested capital
Gas fees can exceed profits
Market conditions can change rapidly

Not Financial Advice:

This tool does not provide financial, investment, or trading advice
Always do your own research (DYOR)
Consult with qualified financial advisors
Understand the risks before trading

No Warranty:

Software provided “as is” without warranty
Authors not liable for financial losses
Use at your own risk

22.2 Responsible Use

Ethical Considerations:

Respect API rate limits
Don’t manipulate markets
Follow platform terms of service
Report bugs and vulnerabilities responsibly

Compliance:

Check local regulations regarding prediction markets
Ensure compliance with applicable laws
Understand tax implications
Verify age and jurisdiction restrictions

23. Support & Contributing

23.1 Getting Help

Issues:

Check existing documentation first
Search closed issues on GitHub
Provide detailed error logs
Include configuration (redact sensitive data)

Community:

Join Discord/Telegram for discussions
Share findings and improvements
Help other users

23.2 Contributing

How to Contribute:

Fork the repository
Create feature branch
Write tests for new features
Follow code style guidelines
Submit pull request with description

Code Standards:

Follow PEP 8 style guide
Add docstrings to functions
Include type hints
Write unit tests (80%+ coverage)
Update documentation

24. Changelog

Version 1.0.0 (Planned)

Initial release
Core scanning functionality
Console and file logging
Basic arbitrage detection
Gas fee estimation

Version 1.1.0 (Future)

Webhook notifications
Enhanced caching
Parallel processing
Performance optimizations

Version 2.0.0 (Future)

Auto-execution capability
Web dashboard
Historical analytics
Machine learning integration

End of Specification