Signalradar

SignalRadar

AI Agent Instructions

When presenting SignalRadar results to the user:

• Always show the market question (slug), current probability, baseline, and absolute change in percentage points.
• For HIT results: highlight the market question, direction of change, and magnitude. Example: "GPT-5 release by June 2026 jumped from 32% to 41% (+9pp), crossing the 5pp threshold."
• For BASELINE results: tell the user "First run — baselines recorded for N markets. Run again later to detect changes." Do not present BASELINE as a problem.
• For NO_REPLY results: briefly confirm "No markets crossed the threshold" — do not dump raw JSON.
• Do not manually edit or delete cache/, config/, or baseline files unless the user explicitly asks. Note: normal runs automatically write baseline and cache files as part of standard operation — this is expected behavior, not a modification you need to initiate.
• Never create cron jobs or scheduled tasks automatically. Always confirm with the user first.
• Do not re-run monitoring in a loop. Run once per user request unless told otherwise.
• When the user says "check markets" or "any market signals", run --mode ai as the default unless a specific mode is requested.

Quick Start

Install

clawhub install signalradar

Verify installation (two steps)

# 1. Health check — confirms Python and network connectivity
python3 scripts/signalradar.py doctor --output json

# 2. Dry-run — fetches live data but does not write state
python3 scripts/signalradar.py run --mode ai --dry-run --output json

Expected: doctor returns {"status": "HEALTHY", ...}. Dry-run returns a JSON object with status being one of NO_REPLY, HIT, or BASELINE.

First run note: The very first run for any mode will return BASELINE — this is normal. SignalRadar records the current probability as a baseline on the first run. Run again later (e.g., after 1 hour) to detect changes against that baseline.

Monitoring Modes

SignalRadar monitors three categories of Polymarket prediction markets. Each mode has its own curated watchlist.

Common flags:

• --dry-run — fetch and evaluate but do not write state or deliver alerts
• --output json — machine-readable JSON output (recommended for AI agents)
• --config /path/to/config.json — use a custom config file

Understanding Results

Every run returns a JSON object. The status field indicates the outcome:

HIT output example

{
  "status": "HIT",
  "request_id": "9f98e47e-6e0e-4563-b7c8-87a3b19e97af",
  "hits": [
    {
      "entry_id": "polymarket:12345:gpt5-release-june:evt_67890",
      "slug": "gpt5-release-june",
      "current": 0.41,
      "baseline": 0.32,
      "abs_pp": 9.0,
      "confidence": "high",
      "reason": "abs_pp 9.0 >= threshold 5.0"
    }
  ],
  "ts": "2026-03-02T08:00:00Z"
}

When presenting a HIT to the user, format it as:

[slug]: [baseline]% -> [current]% (+/-[abs_pp]pp) — [reason]

Configuration

SignalRadar works out of the box with sensible defaults. All configuration is optional.

Key settings

Delivery adapters

• openclaw:direct (default) — delivers to host messaging layer
• file:/path/to/alerts.jsonl — appends alerts to a local JSONL file
• webhook:https://example.com/hook — HTTP POST to external endpoint

For full configuration reference, see references/config.md.

Local State (What This Skill Writes)

During normal operation (without --dry-run), SignalRadar writes the following local files:

Use --dry-run to fetch and evaluate without writing any state. No files outside the skill directory are modified.

Scheduling (Optional)

SignalRadar does not create scheduled tasks automatically. If the user wants periodic monitoring, they can set up system cron:

# Every hour — AI monitoring
0 * * * * cd /path/to/workspace && python3 skills/signalradar/scripts/signalradar.py run --mode ai

# Every 4 hours — Crypto
0 */4 * * * cd /path/to/workspace && python3 skills/signalradar/scripts/signalradar.py run --mode crypto

# Every 6 hours — Geopolitics
0 */6 * * * cd /path/to/workspace && python3 skills/signalradar/scripts/signalradar.py run --mode geopolitics

Optional: Notion Integration

The watchlist-refresh mode syncs the monitoring watchlist from a Notion database. This is the only mode that requires environment variables.

Setup

1. Go to notion.so/my-integrations and click "New integration"
2. Select "Internal" type (NOT OAuth — OAuth is for public apps and requires company info)
3. Name it anything (e.g., "signalradar"), click "Submit"
4. Copy the "Internal Integration Secret" (starts with ntn_)
5. Open your target Notion page, click "..." menu, select "Add connections", choose your integration
6. Copy the page ID from the URL (the 32-character hex string after the page title)
7. Set environment variables:

export NOTION_API_KEY="ntn_xxxxxxxxxxxx"
export NOTION_PARENT_PAGE_ID="32-character-hex-from-page-url"

8. Preview first (recommended): python3 scripts/signalradar.py run --mode watchlist-refresh --dry-run
9. Run: python3 scripts/signalradar.py run --mode watchlist-refresh

Important: watchlist-refresh auto-discovers markets by keyword matching across all active Polymarket markets. It will add 30-50 entries based on configured categories (AI, crypto, geopolitics). To customize which markets are discovered, edit config/watchlist_keywords.json.

Troubleshooting

References

• references/config.md — Full configuration reference
• references/protocol.md — Data contract (EntrySpec, SignalEvent, DeliveryEnvelope)
• references/operations.md — SLO targets, retry policy, observability requirements
• references/notion-sync.md — Notion integration details
• references/platform-adapters.md — Platform adapter specifications