pam ▸ CLAUDE.md
updated 2026-03-15

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

Pam (Prediction Arbitrage Markets) is Unicorn.Land’s prediction market analysis and arbitrage trading system. It ingests RSS feeds, analyzes content, generates trading signals for prediction markets (Kalshi, Polymarket), and executes arbitrage opportunities with human-in-the-loop approval via Telegram.

Commands

source .venv/bin/activate     # Activate venv (or create: python -m venv .venv)
pip install -r requirements.txt

# Database init
python -c "from core.storage import init_database; init_database()"

# Main CLI
python main.py status                       # System status
python main.py run --dry-run                # Dry run signal generation
python main.py run --live --confirm         # Live trading (requires approval)
python main.py webhook --port 5000          # Start Telegram webhook
python main.py test-alert                   # Test Telegram alerts
python main.py arbitrage scan               # Scan for cross-venue arbitrage
python main.py arbitrage execute            # Execute opportunities
python main.py scheduler                    # Background scheduler

# Intra-venue arbitrage
python intraarb.py --venue=polymarket --dryrun
python intraarb.py --venue=kalshi --dryrun=false

# Testing
python -m pytest tests/
python -m pytest arbitrage/intra_venue/tests/

Architecture

Signal Generation Flow

RSS Feeds → Aggregate → Translate → Process → Analyze → Signals
→ Telegram Approval → Order Placement → Execution

Cross-Venue Arbitrage Pipeline

Market Discovery → Cross-Venue Matching → Edge Computation (spread analysis)
→ Position Sizing (Kelly Criterion) → Risk Validation → Atomic Execution

Intra-Venue Arbitrage

Market Loading → Contract Grouping (binary mirrors, ranges)
→ Inconsistency Detection (YES + NO should ≈ 1) → Edge Computation → Atomic Orders

Key Directories

pam/
├── core/                    # Signal system core
│   ├── storage.py           # SQLite database layer
│   ├── ingestion.py         # RSS feed processing
│   ├── signals.py           # Signal generation
│   └── translation.py       # Multi-language support
├── arbitrage/               # Arbitrage detection
│   ├── crypto_scanner.py    # Cross-venue scanner
│   ├── polymarket_api.py    # Polymarket API client
│   ├── kelly_optimizer.py   # Position sizing (Kelly Criterion)
│   ├── liquidity.py         # Liquidity assessment
│   ├── spread_analyzer.py   # Spread calculation
│   └── intra_venue/         # Within-venue arbitrage
│       ├── detector.py      # Inconsistency detection
│       ├── relations.py     # Contract grouping (mirrors, ranges)
│       ├── executor.py      # Execution logic
│       └── router.py        # CLI routing
├── execution/               # Trade execution
│   ├── approvals.py         # Telegram approval workflow
│   └── live_trading.py      # Live trading engine
├── venues/                  # Venue API clients
│   ├── kalshi.py            # Kalshi API
│   └── base.py              # Base venue interface
├── monitoring/              # Alerting
│   └── telegram_bot.py      # Telegram integration
├── main.py                  # Main CLI entry point
├── intraarb.py              # Intra-venue arbitrage CLI
└── config.yaml              # System configuration

Configuration

Environment Variables (.env)

TELEGRAM_BOT_TOKEN=<token>
TELEGRAM_CHAT_ID=<chat_id>
TELEGRAM_ADMIN_IDS=<id1>,<id2>
KALSHI_API_KEY=<key>
POLYMARKET_PRIVATE_KEY=<key>
POLYMARKET_PROXY_ADDRESS=<address>

Config File (config.yaml)

Arbitrage Parameters

Non-Negotiables