Hydra
Docs

How the bot maps Hydra signals to open Polymarket markets.

Correlation Engine

The correlation engine is the core of the bot — it decides whether an incoming Hydra signal is relevant to any open Polymarket market, and scores that relevance.

How It Works

Incoming signal (category, severity, tags, lat/lng)
    ↓
Tag extraction & normalisation
    ↓
Market index lookup (all open markets, refreshed every 15min)
    ↓
Relevance scoring (tag overlap + geographic proximity + category match)
    ↓
Threshold filter (default: score > 0.6)
    ↓
Flagged markets → strategy layer

Relevance Scoring

Each signal-market pair is scored 0–1:

function scoreRelevance(signal: Signal, market: Market): number {
  let score = 0

  // Tag overlap — most weight
  const sharedTags = signal.tags.filter(t => market.tags.includes(t))
  score += (sharedTags.length / Math.max(signal.tags.length, 1)) * 0.5

  // Category → market category match
  const categoryMatch = CATEGORY_MAP[signal.category]?.includes(market.category)
  if (categoryMatch) score += 0.2

  // Geographic proximity — signal lat/lng vs market's implied geography
  const geoScore = getGeoScore(signal, market)
  score += geoScore * 0.2

  // Severity weight — higher severity signals are more likely to be tradeable
  score += (signal.severity / 5) * 0.1

  return Math.min(score, 1)
}

Category → Market Mapping

The engine maps Hydra signal categories to relevant Polymarket market categories:

Signal Category Relevant Market Categories
MISSILE_ALERT geopolitical, conflict, middle-east
NAVAL geopolitical, conflict, china, military
CYBER tech, geopolitical, sanctions
FORCE_DEPLOYMENT conflict, geopolitical, military
MARKET_MOVEMENT economics, geopolitical, sanctions
DIPLOMATIC geopolitical, elections, international

You can override this mapping in config/category-map.ts.

Market Index

The bot maintains a local index of all open Polymarket markets, refreshed every 15 minutes from the Hydra /v1/markets endpoint. Markets are stored with their current prices, tags, volume, and resolution date.

Markets resolving within 24 hours are deprioritised by default (thin liquidity, high spread risk).

Output

The engine emits scored market-signal pairs:

interface CorrelatedMarket {
  signal: Signal
  market: Market
  correlationScore: number     // 0–1
  suggestedOutcome: string     // e.g. "Yes"
  suggestedDirection: 'buy' | 'sell'
  confidence: number           // 0–1
  reasoning: string[]          // human-readable explanation
}

The reasoning field lists the factors that contributed to the score — useful for auditing the bot's decisions.

Bypassing the Engine

You can inject your own correlation logic by implementing the ICorrelationEngine interface:

// src/correlation/my-engine.ts
import type { ICorrelationEngine } from 'hydra-bot'

export class MyCorrelationEngine implements ICorrelationEngine {
  async correlate(signal: Signal, markets: Market[]): Promise<CorrelatedMarket[]> {
    // your logic
  }
}

Then register it in src/index.ts:

const bot = new HydraBot({
  correlationEngine: new MyCorrelationEngine(),
})