Sentinel Watchers

Sentinel watchers are event-driven monitors that poll endpoints and fire webhooks when conditions change. No LLM is involved in the polling loop — the sentinel evaluates conditions locally and only triggers an agent callback when they're met.

This makes sentinels dramatically cheaper than gateway crons for monitoring tasks. A gateway cron checking ETH price every minute costs 1,440 LLM calls/day. A sentinel watcher doing the same costs zero LLM calls until the price actually crosses your threshold.

How It Works

Sentinel polls endpoint (every N ms)
  ├─ Conditions NOT met → do nothing (zero cost)
  └─ Conditions met → fire webhook → agent callback session
                                        └─ LLM processes the event

The sentinel handles:

• HTTP polling with configurable intervals
• JSON path evaluation against response data
• State tracking (knows what changed vs. what was already true)
• Retry with exponential backoff on transient failures
• Optional fireOnce for alert-style triggers

Configuration

{
  "id": "eth-price-alert",
  "strategy": "http-poll",
  "endpoint": "https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd",
  "intervalMs": 60000,
  "match": "all",
  "conditions": [
    { "path": "$.ethereum.usd", "op": "gt", "value": 5000 }
  ],
  "fire": {
    "webhookPath": "/sentinel/eth-price",
    "eventName": "eth-price-above-5k",
    "payloadTemplate": { "price": "${$.ethereum.usd}" }
  },
  "retry": { "maxRetries": 3, "baseMs": 5000, "maxMs": 60000 },
  "fireOnce": true
}

Strategies

Strategy	Use case
http-poll	Most common. Polls an HTTP endpoint at fixed intervals.
evm-call	Reads on-chain contract state via eth_call. No RPC event subscription needed.
websocket	Persistent connection for real-time data feeds.
sse	Server-Sent Events streams.

On-Chain Monitoring with evm-call

The evm-call strategy reads smart contract state directly, using a human-readable ABI signature:

{
  "id": "token-balance-watch",
  "strategy": "evm-call",
  "endpoint": "https://your-rpc-endpoint.example.com",
  "evmCall": {
    "to": "0xTOKEN_CONTRACT_ADDRESS",
    "signature": "function balanceOf(address) view returns (uint256)",
    "args": ["0xYOUR_WALLET_ADDRESS"]
  },
  "intervalMs": 300000,
  "conditions": [
    { "path": "$.result", "op": "changed" }
  ],
  "fire": {
    "webhookPath": "/sentinel/token-balance",
    "eventName": "token-balance-changed",
    "payloadTemplate": { "balance": "${$.result}" }
  }
}

For more complex on-chain queries (transaction history, token transfers, event logs), tools like etherscan CLIs provide account, contract, gas, token, and log query commands that complement sentinel watchers — use blockchain query tools in agent callbacks to enrich the context around sentinel-detected events.

Condition Operators

Operator	Description	Needs value?
eq / neq	Equals / not equals	Yes
gt / gte / lt / lte	Numeric comparison	Yes
contains	String contains	Yes
matches	Regex match	Yes
exists / absent	Field presence	No
changed	Value different from last poll	No

Combine conditions with "match": "all" (AND) or "match": "any" (OR).

Token Cost Advantage

The fundamental cost advantage of sentinels: polling is free, callbacks are cheap.

Approach	Checks/day	LLM calls/day	Cost profile
Gateway cron (15 min)	96	96	Full model cost × 96
Sentinel (1 min poll, ~5 triggers/day)	1,440	~5	Full model cost × 5
Sentinel + fireOnce	1,440	1	One callback, then done

For monitoring tasks, sentinels typically reduce LLM costs by 90-95% compared to equivalent gateway crons.

When to Use Sentinels vs. Crons

Use sentinels when:

• You're watching for a specific condition (price threshold, API error, state change)
• The condition is rarely true (most polls find nothing)
• You need faster-than-cron response time (sentinel can poll every 10s)
• The check can be expressed as a JSON path condition

Use gateway crons when:

• The task requires LLM reasoning every run (summarize emails, analyze data)
• There's no external endpoint to poll (the agent needs to do the checking itself)
• The output is always needed (morning briefing, periodic reports)