OnChainWatcher
OnChainWatcher monitors Polygon on-chain events for a configured list of high-signal wallet addresses, detecting CTFExchangeV2 order fills, position t
What it does
OnChainWatcher monitors Polygon on-chain events for a configured list of high-signal wallet addresses, detecting CTFExchangeV2 order fills, position transfers, and pUSD balance changes that exceed min_position_change_usd. It emits an ObservationReport for each qualifying wallet event after a publish_delay_s hold (to prevent front-running its own signals). Output feeds liquidity-aware strategies and the LiquidityGuard risk bot with smart-money flow intelligence. OnChainWatcher is strictly read-only — it never submits or signs orders.
Pipeline placement
Applies to: All Polymarket markets where watched wallets hold or have recently changed positions
Why it matters
| If this fails | Consequence |
|---|---|
| High-signal wallet entry not detected | Strategy misses a leading indicator; enters after the smart-money move has already re-priced the market, capturing reduced or negative edge. |
| publish_delay_s misconfigured to zero | OnChainWatcher signals are published immediately, allowing the trading infrastructure itself to front-run other participants using its own on-chain data feed. |
| Watched wallet list stale after wallet rotation | Previously high-signal addresses are no longer the active trading wallets; signals become irrelevant and may mislead strategies. |
| RPC outage causes missed position changes during high-activity period | Smart-money entries during the blackout are not detected; strategies enter a market after the signal window has closed. |
Inputs
Polymarket inputs
| Input | Source | Required | Use |
|---|---|---|---|
| CTFExchangeV2 OrderFilled events for watched wallet addresses | onchain (Polygon RPC event log subscription) | required | Primary detection of watched wallet entries and exits in Polymarket markets. |
| pUSD ERC-20 Transfer events for watched wallets | onchain (Polygon RPC) | optional | Detect pUSD balance changes indicating position funding or profit-taking not captured by OrderFilled. |
| Market condition_id from Polymarket Data API for transaction hash mapping | data_api | required | Resolve CTFExchangeV2 token IDs to Polymarket condition_ids in ObservationReport payloads. |
Internal inputs
| Input | Source | Required | Use |
|---|---|---|---|
| watched_wallets list | config / operator-managed registry | required | Filter all Polygon on-chain events to only the configured high-signal wallet addresses. |
| KillSwitch active flag | KillSwitch | required | Continue monitoring on-chain but suppress ObservationReport emissions when KillSwitch is active. |
Authority
What this bot is permitted to do
State
Readiness
Limited live
Status
beta
Class
Signal Service
Default mode
limited_live
Developer owner
Polytraders core — Intelligence pod
Capital impact
Indirect
Reason codes emitted
| Code | Severity | Meaning | Action |
|---|---|---|---|
| ONCHAINWATCHER_LARGE_WALLET_ENTRY | WARN | Watched wallet made a position change >= min_position_change_usd on a Polymarket market. | Emit ObservationReport after publish_delay_s; downstream strategies consume as smart-money signal. |
| ONCHAINWATCHER_SMALL_POSITION | WARN | Wallet position change is between the hard floor (50 pUSD) and default threshold (500 pUSD). | Emit ObservationReport with ONCHAINWATCHER_SMALL_POSITION warning; strategies apply lower weight to this signal. |
| ONCHAINWATCHER_RESOLUTION_RETRY | WARN | token_id could not be resolved to a condition_id via data_api; event buffered for retry. | Buffer event; retry on next block; emit ObservationReport once resolved. |
| STALE_DATA | WARN | RPC provider unresponsive for > 2× poll_interval_s; on-chain state may be stale. | Halt ObservationReport emissions until RPC recovers; alert on-call. |
| KILL_SWITCH_ACTIVE | HARD_REJECT | KillSwitch active; ObservationReport emissions suppressed. | Continue monitoring and queuing events but suppress all emissions. |
| MARKET_CLOSED | EXPLAIN | OrderFilled event received for a condition_id that is already closed or resolved. | Skip emission; log for audit trail only. |
| PARAMETER_CHANGE_REQUIRES_APPROVAL | HARD_REJECT | A parameter change violates a locked bound (e.g. publish_delay_s < 5 or poll_interval_s > 60). | Reject config change; do not apply. |
| ONCHAINWATCHER_EMPTY_WALLET_LIST | WARN | watched_wallets config is empty; no on-chain events will be captured. | Log WARN at startup; emit no ObservationReports until wallets are configured. |
Related bots in Intelligence
Used by
Reverse index — strategies that currently reference intel.onchainwatcher. If you change this bot's authority or reason codes, these strategies must re-pass shadow.
| Strategy | State | Activity |
|---|---|---|
| Crypto Q2 — basket rebalance | frozen | last triggered 30m ago |
| US Elect — book-builder | demo-wired | last triggered 37m ago |
Showing 2 of 2 · demo-wired ≠ production-live
Why this matters
Intelligence bots does NOT propose, veto, sign, or execute any trade. Understanding the authority boundary prevents misuse and makes promotion-gate reviews faster and more reliable. View raw spec JSON →