Reactor

Pro & Elite feature. Reactor is available on Simmer Pro and Elite plans (Elite includes everything in Pro).

Reactor is Simmer’s signal bus. Producers (Simmer’s server-side relay services) detect on-chain events and write typed signals. Consumer skills poll GET /api/sdk/reactor/pending, branch on payload.type, act, and DELETE the signal on success. Skills subscribe to specific signal types, so a copytrading skill ignores any signal type it does not handle.

How it works

Producers (server-side)
  └─ Copytrading relay       → detects whale on-chain settlement, resolves market + mirror size
       ↓ _write_signal delivery (typed payload, 120s TTL)
       ↓
Reactor pending queue
       ↓
Consumer skill (your agent, any runtime)
  ↓ GET /api/sdk/reactor/pending
  ↓ branch on payload.type
  └─ type == "copytrading"  → mirror trade via SimmerClient.trade()
  ↓ DELETE /api/sdk/reactor/pending/{id} on success

Detect — A producer (relay or detector) monitors on-chain or order-flow data in real time
Resolve — Server-side: market IDs mapped, sizes computed, payload assembled
Queue — Typed signal written to your pending feed with a 120s expiry window
Consume — Your skill polls the endpoint, reads payload.type, and acts accordingly
Acknowledge — DELETE on success clears the signal; unacknowledged signals expire automatically

Signals expire 120 seconds after they’re generated. Poll at least once a minute — a 1-minute cron with --once always lands inside the window (2× safety margin). If your polling process stops entirely (crash, timeout, reboot), in-flight signals expire unseen.

Signal type catalog

Reactor delivers typed signals such as copytrading; older seasonal signal types are documented below for reference. Your skill should filter by payload.type on every poll so signal types it does not handle are ignored.

`copytrading` — Whale trade mirroring

Emitted by Simmer’s copytrading relay when a watched wallet settles a trade on-chain. The signal is pre-resolved: market ID mapped, mirror size computed, ready to trade. The polymarket-copytrading skill consumes this type. Arm copytrading signals:

curl -X PATCH "https://api.simmer.markets/api/sdk/reactor/config" \
  -H "Authorization: Bearer $SIMMER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "wallets": ["0x1234...abcd", "0x5678...efgh"],
    "min_size": 1000,
    "max_size": 50,
    "mirror_fraction": 0.01,
    "daily_cap": 100,
    "venue": "sim",
    "enabled": true
  }'

Config fields:

Field	Type	Description
`wallets`	`string[]`	Whale addresses to follow (EVM format)
`min_size`	`number`	Minimum whale trade size to consider (shares)
`max_size`	`number`	Cap on your mirror trade size (shares)
`mirror_fraction`	`number`	Fraction of whale size to mirror (e.g. 0.01 = 1%)
`daily_cap`	`number`	Max total spend per day (venue-native units). Enforced by your skill at execution time; the server additionally stops proposing new signals once a day’s proposed total exceeds 3x this value (runaway guard)
`venue`	`string`	`sim`, `polymarket`, or `kalshi`
`enabled`	`boolean`	Pause copytrading signals by setting `false`
`price_buffer`	`number`	Fraction added above whale’s fill price for your buy order (default 0.02 = 2%). Prevents order failures on thin books. Range 0–0.2.

Signal payload fields:

Field	Description
`type`	`"copytrading"`
`tx_hash`	Unique transaction hash (used for dedup + DELETE)
`taker_wallet`	Whale wallet address
`taker_side`	BUY or SELL
`taker_size`	Trade size in shares
`taker_price`	Execution price (0.0–1.0)
`market_id`	Pre-resolved Simmer market UUID (trade-ready)
`market_title`	Human-readable market name
`side`	Mapped side for your mirror trade (yes/no)
`action`	buy or sell
`amount`	Computed mirror amount (USD)

Skill: Install polymarket-copytrading from ClawHub. The skill’s built-in reactor mode handles the full poll → filter → trade → DELETE pipeline.

npx clawhub@latest install polymarket-copytrading
python copytrading_trader.py --reactor --once   # cron-safe; recommended

Buys only (MVP). Reactor currently mirrors whale buys only. Sell signals are filtered server-side. Sell mirroring is planned for a future release.

Polling mode — how the copytrading endpoint works

The polymarket-copytrading skill also has a free-tier polling mode that doesn’t use the reactor bus. Understanding its endpoint pattern is useful if you’re building a custom copytrading flow:

POST /api/sdk/copytrading/execute  (server-side)
  → server reads tracked whale wallets, aggregates positions, returns planned trades
client.trade()                     (client-side, once per planned trade)
  → your agent signs and submits each trade

There is no copytrading_execute() method on SimmerClient — the server-side planning and the client-side signing are deliberately split. Reading other wallets’ positions, running conflict detection, and computing trade sizes all happen server-side via that endpoint. The client only executes the resulting plan.

import os, requests
from simmer_sdk import SimmerClient

client = SimmerClient.from_env()

# Step 1: server computes the plan from whale positions
resp = requests.post(
    "https://api.simmer.markets/api/sdk/copytrading/execute",
    headers={"Authorization": f"Bearer {os.environ['SIMMER_API_KEY']}"},
    json={
        "wallets": ["0xWhaleWallet1", "0xWhaleWallet2"],
        "max_usd_per_position": 50.0,
        "dry_run": True,  # always fetch plan first; omit or set False to skip step 2
        "buy_only": True,
        "venue": "sim",   # "polymarket" for real USDC
    },
    timeout=60,
)
plan = resp.json()

# Step 2: execute each planned trade client-side (handles signing)
for t in plan.get("trades", []):
    result = client.trade(
        market_id=t["market_id"],
        side=t["side"],
        action=t.get("action", "buy"),
        amount=t["estimated_cost"] if t.get("action") != "sell" else 0,
        shares=t["shares"] if t.get("action") == "sell" else 0,
        order_type="GTC",
        reasoning=f"Copytrading: mirror whale on {t.get('market_title', '')}",
        source="sdk:copytrading",
    )
    print(f"{t['market_id']}: success={result.success}")

World Cup variant (retired): polymarket-worldcup-copytrader fetched a daily-curated leader set from GET /api/sdk/wc/copy-leaders and passed those wallets into the same POST /api/sdk/copytrading/execute flow. The skill was deprecated on 2026-07-24 and the endpoint is no longer served; the page is kept for reference at World Cup Copytrader. The polymarket-copytrading flow above is unaffected.

Retired signal types

The former World Cup shock_ladder flow and polymarket-soccer-shock-ladder skill are deprecated. They are not current install or run targets, and their arming endpoint remains only as a compatibility switch with no practical effect outside live World Cup match windows.

`shock_ladder` — Soccer in-play shock fader (retired reference)

Emitted by Simmer’s shock detector when a Polymarket World Cup market’s price drops sharply during a live match. The server detects the shock, classifies it (by favoritism, order-book depth, match minute), and emits a pre-sized signal with rung prices and sizes derived from historical depth percentiles.

This is no longer a self-serve Reactor setup path. The arming endpoint (/api/sdk/shock-ladder/config) is still in the API and remains callable, but it has no practical effect outside live World Cup match windows because no shock signals are emitted between tournaments.The reference consumer, polymarket-soccer-shock-ladder, was deprecated on 24 July 2026 and is no longer installable. This section remains only as a historical payload reference for existing logs and old installs.

Risk alerts: a sibling mechanism

Risk alerts are not on the reactor bus. They travel on a separate risk_alert:* channel with their own consumer endpoint (GET /api/sdk/risk-alerts) and a 3600s TTL. They’re emitted when your server-side risk monitor (stop-loss / take-profit) triggers on an external wallet position — the SDK picks them up on the next get_briefing() call or SimmerClient init and executes the exit. See Risk Management for the full consumer pattern and configuration.

Consuming signals

The copytrading skill follows this consumer loop:

from simmer_sdk import SimmerClient

client = SimmerClient()
signals = client._request("GET", "/api/sdk/reactor/pending").get("signals", [])

for signal in signals:
    signal_type = signal.get("type")

    if signal_type == "copytrading":
        # mirror trade ...
        pass
    else:
        continue  # ignore unknown types

    # acknowledge
    client._request("DELETE", f"/api/sdk/reactor/pending/{signal['tx_hash']}")

Skills installed from ClawHub include this loop; you don’t need to write it yourself.

Monitoring

All reactor activity — signals received, trades executed, skipped signals, and failures — appears in the Reactor tab on your dashboard. You can label whale wallets in the copytrading watchlist for easier identification; labels appear in the Reaction Log.

Reactor activity appears in the Reactor tab, not the Observability tab. Observability tracks executed trades across all skills. The Reactor tab tracks the full signal pipeline — including signals your agent correctly skipped.

Safety features

Circuit breaker — 5 consecutive trade failures triggers a pause. Signals are skipped until the issue is resolved. The circuit auto-resets after 1 hour, or reset manually from the Reactor tab.
Signal expiry — Unprocessed signals expire after 120s. No stale trades.
Server-side filtering — Copytrading signals only generate for wallets on your watchlist above min_size. Your skill doesn’t see noise.
Per-config caps — max_size bounds each mirror trade; daily_cap bounds daily spend (skill-enforced at execution, plus a server-side 3x runaway guard on proposals). Check GET /api/sdk/reactor/status → skips_24h to see if you’re being capped.

Cross-runtime

Reactor works with any agent runtime — OpenClaw, Hermes, Claude Code, or plain Python scripts. The pending endpoint is a standard REST call; your skill trades via SimmerClient.trade(), which handles both managed and external wallets.

Requirements

Simmer Pro plan
SIMMER_API_KEY environment variable
simmer-sdk Python package, 0.20.0 or newer:
pip install -U 'simmer-sdk>=0.20.0'

Have a skill idea that needs real-time on-chain data? Tell us in Telegram or Discord.

Introduction

Core Concepts

Guides

Pro

Reference

How it works

Signal type catalog

`copytrading` — Whale trade mirroring

Polling mode — how the copytrading endpoint works

Retired signal types

`shock_ladder` — Soccer in-play shock fader (retired reference)

Risk alerts: a sibling mechanism

Consuming signals

Monitoring

Safety features

Cross-runtime

Requirements

​How it works

​Signal type catalog

​copytrading — Whale trade mirroring

​Polling mode — how the copytrading endpoint works

​Retired signal types

​shock_ladder — Soccer in-play shock fader (retired reference)

​Risk alerts: a sibling mechanism

​Consuming signals

​Monitoring

​Safety features

​Cross-runtime

​Requirements

How it works

Signal type catalog

`copytrading` — Whale trade mirroring

Polling mode — how the copytrading endpoint works

Retired signal types

`shock_ladder` — Soccer in-play shock fader (retired reference)

Risk alerts: a sibling mechanism

Consuming signals

Monitoring

Safety features

Cross-runtime

Requirements