prediction-market-arbitrageur

name	prediction-market-arbitrageur
description	Meta-skill for orchestrating topic-monitor, polymarket-odds, and simmer-weather to detect potential news-vs-market mispricing in prediction markets. Use when users want a clear, step-by-step LM workflow for monitoring breaking signals, reading current Polymarket probabilities, computing confidence/price deltas, and producing alert-first arbitrage decisions.
homepage	https://clawhub.ai
user-invocable	true
disable-model-invocation	false
metadata	{"openclaw":{"emoji":"chart_with_upwards_trend","requires":{"bins":["python3","node","npx"],"env":["SIMMER_API_KEY"],"config":[]},"note":"Requires local installation of topic-monitor, polymarket-odds, and simmer-weather via ClawHub."}}

Purpose

Use this meta-skill to coordinate three existing ClawHub skills into one causal arbitrage workflow:

1. Detect new high-signal news about a target event.
2. Fetch current market-implied probability from Polymarket.
3. Compare news confidence vs market probability.
4. Emit actionable alert, optionally followed by explicit execution guidance.

This skill does not replace the underlying skills. It defines how to combine them correctly.

Required Installed Skills

This meta-skill assumes these are already installed locally:

• topic-monitor (inspected: latest 1.3.4)
• polymarket-odds (inspected: latest 1.0.0)
• simmer-weather (inspected: latest 1.7.1, execution proxy pattern)

Install/refresh with ClawHub:

npx -y clawhub@latest install topic-monitor
npx -y clawhub@latest install polymarket-odds
npx -y clawhub@latest install simmer-weather
npx -y clawhub@latest update --all

Verify:

npx -y clawhub@latest list
python3 skills/topic-monitor/scripts/monitor.py --help
node skills/polymarket-odds/polymarket.mjs --help
python3 skills/simmer-weather/weather_trader.py --help

If any command fails, stop and report missing dependency or wrong install path.

Inputs the LM Must Collect First

• ceo_name
• company_name
• event_hypothesis (for example: CEO X resigns within 30 days)
• market_query (for polymarket search)
• topic_id (stable ID in topic-monitor)
• monitor_interval_minutes (default: 5)
• min_news_confidence (default: 0.80)
• min_delta (default: 0.25)
• execution_mode (alert-only or execution-plan)

Do not continue with implicit trading assumptions if these are missing.

Skill Responsibilities (What Each Tool Actually Does)

topic-monitor

Use for continuous signal discovery and scoring.

Operationally relevant behavior:

• Topic config via scripts/manage_topics.py.
• Monitoring loop via scripts/monitor.py.
• Priority/score generated by its scoring logic.
• Alert queue retrieval via scripts/process_alerts.py --json.

This is the source of news confidence candidates.

polymarket-odds

Use for live market probability lookups.

Operationally relevant behavior:

• search <query> to find matching events/markets.
• market <slug> to inspect specific market pricing.
• Outputs percentage-formatted odds that must be normalized to [0,1].

This is the source of market probability.

simmer-weather

Primary design is weather strategy, but in this chain it is treated as execution proxy reference because it uses Simmer SDK trade endpoints and live/dry-run safety pattern.

Operationally relevant behavior:

• Requires SIMMER_API_KEY.
• Supports dry-run and live execution modes.
• Demonstrates guarded trading workflow and position checks.

In this meta-skill, it is not the signal engine. It is the execution pattern reference.

Canonical Causal Chain

Use this exact chain:

1. topic-monitor heartbeat every 5 minutes.
2. Match target rumor pattern (resignation, ceo_name, company_name).
3. Accept only high-confidence signal (news_confidence >= 0.80).
4. Query polymarket-odds for matching market and read current yes probability.
5. Compute delta = news_confidence - market_probability.
6. If delta >= min_delta, trigger arbitrage alert.
7. If execution_mode=execution-plan, output explicit next trading step; do not auto-trade unless user explicitly asks.

Data Contract Between Skills

Normalize all values into one record before decisioning:

{
  "topic_id": "ceo-resignation-acme",
  "event_hypothesis": "CEO X resigns",
  "news_confidence": 0.82,
  "news_signal_time": "2026-02-14T14:05:00Z",
  "market_slug": "will-ceo-x-resign",
  "market_probability": 0.40,
  "market_snapshot_time": "2026-02-14T14:06:00Z",
  "delta": 0.42,
  "decision": "buy_yes_candidate"
}

Hard rules:

• Reject stale signal if news_signal_time is older than 30 minutes.
• Reject stale market snapshot older than 5 minutes.
• Never compare percentages and decimals mixed. Convert all to decimals first.

LM Execution Playbook

Step A: Configure topic once

python3 skills/topic-monitor/scripts/manage_topics.py add \
  "CEO Resignation - <company_name>" \
  --id <topic_id> \
  --query "<ceo_name> resignation <company_name> CEO stepping down" \
  --keywords "resignation,<ceo_name>,<company_name>,CEO,board,step down" \
  --frequency hourly \
  --importance high \
  --channels telegram \
  --context "Prediction market mispricing detection"

Step B: Run heartbeat loop externally (every 5 min)

python3 skills/topic-monitor/scripts/monitor.py --topic <topic_id> --force
python3 skills/topic-monitor/scripts/process_alerts.py --json

Use max recent score for confidence extraction.

Step C: Pull market probability

node skills/polymarket-odds/polymarket.mjs search "<market_query>"
node skills/polymarket-odds/polymarket.mjs market <market_slug>

Extract yes-price and normalize (40% -> 0.40).

Step D: Decide

Formula:

• delta = news_confidence - market_probability
• Trigger if news_confidence >= min_news_confidence and delta >= min_delta

Step E: Emit output

If triggered, emit:

🚨 ARBITRAGE: News bestätigen, Markt schläft. Kauf empfohlen.

Plus structured fields:

• news_confidence
• market_probability
• delta
• signal_age_minutes
• market_age_minutes
• recommendation

Output Modes

alert-only

Return recommendation and confidence math only. No execution step.

execution-plan

Return recommendation plus explicit manual next actions using installed simmer-weather runtime pattern:

• check API key present
• run dry-run first
• require explicit user confirmation before any live action

Guardrails for the LM

• Do not fabricate market slugs or prices.
• Do not promote execution when confidence math is below threshold.
• Do not issue live-trade instructions without clear user opt-in.
• Surface uncertainty explicitly when matching query to market is ambiguous.
• Prefer false-negative over false-positive when news credibility is weak.

Failure Handling

• Missing skill install: output exact missing path/command.
• Missing env var (SIMMER_API_KEY): degrade to alert-only.
• No market match: return no_trade with retry query suggestions.
• Conflicting signals: require two independent high-confidence hits before alerting.

Why This Meta-Skill Exists

Without orchestration, each tool solves only a fragment:

• topic-monitor detects events but has no market-price context.
• polymarket-odds shows prices but no external signal confidence.
• simmer-weather demonstrates execution mechanics but is not a generic event detector.

This meta-skill binds those fragments into one coherent arbitrage decision process that an LM can execute consistently.