Oddy CLI

Command-line interface for Oddy prediction market intelligence. Analyze traders, track top performers, and discover convergence signals—all from your terminal.

Perfect for AI agents (Claude, custom bots) to access Oddy's intelligence layer programmatically.

Installation

npm install -g @oddy/cli

Quick Start

# 1. Get your API key from https://app.getoddy.io/settings/api
# 2. Authenticate
oddy login od_live_your_key_here

# 3. Analyze a wallet (discovery workflow)
oddy analyze 0x1234567890123456789012345678901234567890

# 4. Browse top traders
oddy traders --limit 20

# 5. Find convergence signals
oddy signals --min-traders 5

Discovery Workflow

The primary use case: Find wallets on Twitter/social media, validate if they're actually good traders.

# Someone tweets a wallet address
# Step 1: Analyze it
$ oddy analyze 0xabc123...

📊 Wallet Analysis
Address: 0xabc123...

✅ LEADERBOARD QUALIFIED
   Oddy Score: 65 (Threshold: 40)
   Rank: #245

Performance
  Total PnL: $15,420.50
  Win Rate: 72.5%
  ROI: 18.2%
  Volume: $85,340
  Trades: 145 (105W / 40L)

💡 Recommendation
  STRONG - Top tier trader worth tracking

# Step 2: Add to watchlist
$ oddy watch 0xabc123... --label "Twitter discovery"

# Step 3: Monitor
$ oddy watchlist

Command Reference

Authentication

oddy login <api-key>       # Authenticate with API key
oddy logout                # Remove stored credentials
oddy whoami                # Show current auth status

Analysis

oddy analyze <address>     # Analyze any wallet (triggers enrichment if new)

Output:

• Oddy Score & leaderboard qualification
• Performance metrics (PnL, win rate, ROI, volume)
• Trading style (day trader, swing trader, position trader)
• Data quality (days synced, verification status)
• Recommendation (strong/moderate/weak)

Traders

oddy traders               # Get top trader leaderboard
  --limit <number>         # Number of results (default 20, max 500)
  --sort <field>           # Sort by: oddyScore, totalPnl, winRate, roi
  --min-score <number>     # Minimum Oddy Score (default 40)

oddy trader <address>      # Detailed trader profile
oddy positions <address>   # Current open positions
oddy trades <address>      # Recent trade history
  --limit <number>         # Number of trades (default 20)
  --market <id>            # Filter by specific market

Markets

oddy markets               # Markets with top trader activity
  --limit <number>         # Number of results (default 20)
  --category <name>        # Filter: Crypto, Sports, Politics, etc.
  --min-traders <number>   # Minimum positioned traders (default 3)
  --sort <field>           # Sort by: topHolderCount, topHolderValue, volume24h

oddy market <id>           # Detailed market information

Market output shows:

• Positioned top traders by side (YES/NO)
• Sentiment scores (-1 bearish to +1 bullish)
• Money flow analysis (buy vs sell volume)
• Individual trader breakdown

Signals

oddy signals               # Convergence signals (3+ aligned traders)
  --limit <number>         # Number of results (default 10)
  --min-traders <number>   # Minimum aligned traders (default 3)
  --min-sentiment <number> # Sentiment threshold (default 0.4)

Shows:

• Markets where 3+ top traders are on the same side
• Convergence strength (% aligned)
• Money flow confirmation
• Top aligned traders with scores

Watchlist

oddy watchlist             # View your tracked wallets
oddy watch <address>       # Add wallet to watchlist
  --label <name>           # Optional nickname
oddy unwatch <address>     # Remove wallet from watchlist

Use Cases

1. Wallet Discovery

Find and validate wallets from social media:

# Found on Twitter
oddy analyze 0x1234...

# If good, track it
oddy watch 0x1234... --label "Crypto Twitter"

# Monitor performance
oddy watchlist

2. Copy Trading Research

Find top traders in specific niches:

# Top crypto traders
oddy traders --sort oddyScore --category Crypto --limit 10

# Analyze their current positions
oddy positions <top-trader-address>

# See what they're trading
oddy trades <top-trader-address>

3. Signal Monitoring

Find strong convergence signals:

# High-confidence signals
oddy signals --min-traders 5 --min-sentiment 0.6

# Check market details
oddy market <market-id-from-signal>

4. Market Intelligence

Research specific markets:

# Sports markets with activity
oddy markets --category Sports --min-traders 5

# Deep dive
oddy market polymarket-0xabc...

Key Concepts

Oddy Score (0-100):

• Proprietary performance metric
• Combines PnL, win rate, consistency, risk-adjusted returns
• 40+ = Leaderboard qualified
• 60+ = Top tier
• 80+ = Elite

Top Trader:

• Wallet with Oddy Score ≥ 40
• Top 500 tracked on leaderboard

Sentiment (-1 to +1):

• -1 = Bearish (selling YES / buying NO)
• 0 = Neutral (split)
• +1 = Bullish (buying YES / selling NO)

Money Flow:

• Directional trading from top 500 traders (7-day window)
• Compares buy volume vs sell volume

Convergence:

• 3+ top traders aligned on same side
• Ratio > 2:1 vs opposite side

Verified Wallet:

• 30+ days of blockchain-validated history
• Higher data quality

For AI Agents (Claude, Custom Bots)

The CLI is designed for AI agent integration:

Claude Desktop: Install CLI globally, authenticate once, then Claude can run commands naturally.

Example Claude workflow:

User: "Find me the best sports traders"
Claude: oddy traders --category Sports --sort oddyScore --limit 10

User: "Analyze the #1 trader"
Claude: oddy trader <address-from-previous>

User: "What are they holding?"
Claude: oddy positions <address>

Custom Bots: Use CLI or call API directly:

• Base URL: https://api.getoddy.io/v1
• Auth: Authorization: Bearer od_live_...
• See docs/api/INTELLIGENCE_API.md for full API docs

Configuration

Config stored in: ~/.config/oddy-cli/config.json

Set custom API URL:

export ODDY_API_URL=http://localhost:3000/api/v1
oddy whoami

Rate Limits

| Tier | Requests/Minute | |------|----------------| | Free | 60 | | Pro | 300 | | Enterprise | 1000 |

Examples

Discover a wallet:

oddy analyze 0x40e5e171884f1c2a6e3021dfa9e297d268a1f7ec

Top 10 by profit:

oddy traders --sort totalPnl --limit 10

Crypto markets with strong signals:

oddy markets --category Crypto --min-traders 5
oddy signals --category Crypto --min-traders 3

Monitor a specific trader:

oddy trader 0x84cb17a50bc2487e8d64029783c3d2abcba328ad
oddy positions 0x84cb17a50bc2487e8d64029783c3d2abcba328ad
oddy trades 0x84cb17a50bc2487e8d64029783c3d2abcba328ad --limit 50

Support

• Docs: https://docs.getoddy.io
• API Reference: https://docs.getoddy.io/api
• Discord: https://discord.gg/oddy
• Email: [email protected]

License

MIT