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.

Mode	Command	What it covers
ai	python3 scripts/signalradar.py run --mode ai	AI model releases, AGI timelines, AI regulation
crypto	python3 scripts/signalradar.py run --mode crypto	Bitcoin, Ethereum, DeFi, stablecoin events
geopolitics	python3 scripts/signalradar.py run --mode geopolitics	Elections, conflicts, sanctions, treaties
watchlist-refresh	python3 scripts/signalradar.py run --mode watchlist-refresh	Refreshes watchlist by keyword-matching active Polymarket markets (requires Notion env vars). Warning: this auto-discovers markets by category keywords and may add 30-50 entries. Use --dry-run first to preview.

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:

Status	Meaning	What happens
BASELINE	First observation for an entry	Baseline recorded; no alert sent
SILENT	Change is below threshold	No alert sent
HIT	Change exceeds threshold	Alert emitted via delivery adapter
NO_REPLY	No entries crossed threshold this run	Nothing to report

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

Setting	Default	Description
threshold.abs_pp	5.0	Global threshold in percentage points
threshold.per_category_abs_pp	varies	Per-category override (e.g., AI: 4.0, Crypto: 8.0)
baseline.cleanup_ttl_days	45	Auto-cleanup stale baselines after N days
delivery.primary.channel	openclaw	Delivery adapter: openclaw:direct, file:/path, webhook:https://...

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:

Path	Purpose	When written
cache/baselines/*.json	Stores last-seen probability for each market	Every non-dry-run, to enable change detection
cache/events/*.jsonl	Audit log of all decisions (HIT/SILENT/BASELINE)	Every non-dry-run
memory/polymarket_watchlist_2026.md	Watchlist table for ai mode	Only by watchlist-refresh mode

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

Error Code	Cause	Fix
SR_TIMEOUT	Polymarket API did not respond within timeout	Check network connectivity; retry after 30s. If persistent, the API may be down.
SR_SOURCE_UNAVAILABLE	Cannot reach gamma-api.polymarket.com	Verify DNS resolution and internet access. Check if a proxy/VPN is blocking the request.
SR_VALIDATION_ERROR	Malformed entry data or schema mismatch	Run python3 scripts/validate_schema.py to identify the invalid field. Check config/watchlist_keywords.json.
SR_ROUTE_FAILURE	Delivery adapter failed to send alert	Check delivery config in config.json. For webhook: verify endpoint is reachable. For file: verify write permissions.
SR_CONFIG_CONFLICT	Contradictory config values	Review config.json for duplicate keys or invalid combinations. See references/config.md.
SR_PERMISSION_DENIED	Insufficient permissions for Notion API	Re-check NOTION_API_KEY and ensure the integration has access to the target page.
SR_AUTH_MISSING	Required Notion env vars not set	Set NOTION_API_KEY and NOTION_PARENT_PAGE_ID. Only needed for watchlist-refresh mode.
SR_NOTION_PAGE_NOT_FOUND	Notion page ID does not exist or is not shared	Verify NOTION_PARENT_PAGE_ID is correct (32-char hex). Ensure page is shared with the integration.
SR_NOTION_READ_FAILURE	Failed to read from Notion API	Check Notion API status. Verify the integration has read access to the page.
SR_NOTION_WRITE_FAILURE	Failed to write to Notion API	Check Notion API status. Verify the integration has write (insert content) permission.

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