How Background Alerts Work
Native Mobile (Capacitor)
On iOS and Android, Chainfolio uses Capacitor Background Runner—a native framework for running JavaScript in the background.
- Scheduled execution – Runs every 15‑30 minutes based on OS constraints
- Isolated process – Separate from main app to conserve battery
- Native push notifications – Uses iOS/Android notification systems
- Battery optimization – Automatically adjusts frequency based on usage patterns
- Network‑aware – Can wait for WiFi to avoid mobile data usage
Web Browser (Service Workers)
In browsers, Chainfolio uses Service Workers with Periodic Background Sync.
- Browser support – Chrome, Edge, Safari (with limitations)
- Periodic Sync API – Runs when browser is open (even if tab closed)
- Push API – Browser‑based push notifications
- Offline‑first – Can evaluate alerts with cached data if network unavailable
- Permission‑based – Requires user grant for background sync
Architecture: No Server Dependency
Traditional Alert Services
- Your wallet addresses stored on their servers
- Alert logic runs on their infrastructure
- They know when and why you get alerts
- Require accounts and authentication
Chainfolio Background Alerts
- Alert evaluation happens on your device
- No server ever sees your alert conditions
- Push notifications via local OS mechanisms
- No accounts, no telemetry, no data sharing
Privacy Guarantee
- Your alert rules stored in encrypted local database
- Evaluation uses only local data + RPC calls
- Notification content never leaves device
- Revocable at any time (delete app = delete alerts)
Step 1: Enable Background Processing
Mobile App (iOS/Android)
- Install Chainfolio mobile app via Capacitor (build from source or download)
- On first launch, grant Background App Refresh permission when prompted
- For iOS: Enable Background Modes → Background Fetch in system settings
- For Android: Grant Battery Optimization exemption for Chainfolio
- Verify background capability:
- iOS: Settings → Chainfolio → Background App Refresh = ON
- Android: Settings → Apps → Chainfolio → Battery → Unrestricted
Web Browser
- Open Chainfolio in supported browser (Chrome/Edge recommended)
- When prompted, allow notifications (click "Allow" in browser prompt)
- Grant background sync permission (may appear as separate prompt)
- Verify Service Worker registration:
- Chrome: DevTools → Application → Service Workers (should show "activated")
- Settings → Background Alerts → Status should show "Service Worker active"
- For best results, keep browser running (can be minimized)
Step 2: Create Your First Alert
Alert Creation Interface
- Navigate to Alerts → Create New Alert
- Select alert type:
- Portfolio Value – Total portfolio across all chains
- Wallet Balance – Specific Ethereum or Solana wallet
- Token Price – Specific token (BTC, ETH, SOL, etc.)
- RPC Health – Endpoint latency, error rate, sync status
- Whale Movement – Tracked whale activity (requires Whale Watcher)
- Custom Condition – Advanced logical combinations
- Configure trigger parameters (thresholds, operators, time windows)
- Set notification preferences (push, in‑app, or both)
- Name your alert for easy identification
- Click Save & Activate
Common Alert Templates
Portfolio Protection
"Notify me if my total portfolio drops by 10% in 24 hours"
Price Target
"Notify me when BTC price exceeds $75,000 or falls below $60,000"
RPC Degradation
"Notify me if RPC latency exceeds 2 seconds or error rate > 5%"
Whale Signal
"Notify me when any tracked whale moves > $1M to an exchange"
Alert Configuration Options
- Threshold types – Absolute value, percentage change, relative to ATH
- Time windows – 1h, 24h, 7d, 30d, or custom duration
- Operators – >, <, >=, <=, ==, percentage change up/down
- Aggregation methods – Any, all, average, minimum, maximum
- Condition chaining – AND/OR logic across multiple conditions
- Recipient targeting – Which wallets/chains/tokens to monitor
Step 3: Configure Advanced Alert Logic
Condition Builder
Chainfolio's alert system supports complex logical conditions using AND/OR operators:
Example: Market Downturn Protection
IF (portfolio_drop > 15% in 24h) AND (btc_dominance_increasing) AND (fear_greed_index < 20)
THEN alert_level = "CRITICAL"
Example: DeFi Risk Monitoring
IF (defi_exposure > 40% of portfolio) AND (protocol_concentration > 20% in single protocol)
THEN alert_level = "HIGH"
Example: Whale‑Like Behavior
IF (portfolio_value > $1M) AND (solana_balance > 10,000 SOL) AND (hourly_tx_count < 3)
THEN alert_level = "MEDIUM"
Time‑Based Conditions
Configure alerts that consider time of day, day of week, or specific dates:
- Market hours – Only alert during trading hours (9:30AM‑4PM ET)
- Weekend sensitivity – Different thresholds for weekends vs weekdays
- Event‑based – Alert around known events (Fed meetings, CPI releases)
- Sleep hours – Mute notifications during specified hours
- Recurring patterns – Alert on specific days (e.g., monthly options expiry)
Multi‑Condition Logic
Combine multiple conditions with advanced logic:
- Nested conditions – (A AND B) OR (C AND D)
- Weighted scoring – Assign weights to different conditions
- Sequential triggers – Condition B only matters if Condition A triggered first
- Stateful conditions – Remember previous triggers for pattern detection
- Cross‑chain conditions – Combine Ethereum and Solana metrics
Step 4: Configure Notification Preferences
Delivery Methods
- Push notifications – iOS/Android native or browser push
- In‑app notifications – Visible only when app is open
- Email fallback – Optional (requires email configuration)
- Webhook integration – Advanced: POST to custom endpoint
Notification Content
- Rich notifications – Include charts, token icons, action buttons
- Customizable templates – Control what information is shown
- Priority levels – Critical/High/Medium/Low affect delivery timing
- Grouping – Similar alerts grouped into single notification
Quiet Hours & Cooldown
- Sleep schedule – No notifications between specified hours
- Per‑alert cooldown – Don't alert twice for same condition within X minutes
- Global rate limiting – Max X notifications per hour/day
- Escalation bypass – Critical alerts always fire regardless of cooldown
Risk‑Level Classification
Alerts are automatically classified by risk level to avoid notification fatigue:
- LOW – Informational (e.g., daily portfolio summary, whale added new token)
- MEDIUM – Worth attention (e.g., 10% portfolio move, whale moved > $500K to exchange)
- HIGH – Actionable (e.g., large withdrawal to exchange, RPC consistently failing)
- CRITICAL – Immediate attention (e.g., portfolio dropped 25% in 1h, RPC completely down)
Step 5: Monitor & Manage Active Alerts
Alert Dashboard
Monitor all active alerts and their status:
- Active alerts – Currently monitoring and evaluating
- Recent triggers – History of fired alerts with timestamps
- Success rate – Percentage of evaluations that resulted in alerts
- Next evaluation – When each alert will next be checked
- Resource usage – Battery/data impact of each alert
Alert Management
Control your alerts after creation:
- Enable/disable – Temporarily pause alerts without deleting
- Edit in place – Modify thresholds or conditions
- Duplicate – Create similar alerts with minor changes
- Export/import – Backup alert configurations or share with others
- Bulk operations – Enable/disable/delete multiple alerts at once
Advanced: Alert Groups & Scenarios
Portfolio Protection Group
Configuration: Create a group of alerts that work together to protect your portfolio. Example: "If portfolio drops 10% AND BTC dominance rising AND fear/greed extreme fear → CRITICAL alert."
DeFi Risk Monitoring Group
Configuration: Monitor multiple DeFi‑specific risks simultaneously. Example: "If impermanent loss > 5% OR protocol TVL dropped 30% OR APY fell below benchmark."
Whale Signal Group
Configuration: Combine multiple whale‑related alerts for comprehensive monitoring. Example: "If 3+ whales move to same exchange OR whale buys token you hold > $1M volume."
RPC Infrastructure Group
Configuration: Monitor your entire RPC infrastructure health. Example: "If any endpoint latency > 2s OR success rate < 90% OR sync behind > 100 blocks."
Troubleshooting Alert Issues
Alerts Not Firing
Solution: Check background processing permissions. On iOS/Android, ensure Background App Refresh is enabled. On web, check Service Worker status in browser devtools.
Delayed Notifications
Solution: Background processing runs on OS‑controlled schedules (every 15‑30 minutes). Critical alerts can be configured to trigger immediate in‑app notifications even between background runs.
Battery Drain Concerns
Solution: Reduce alert evaluation frequency or number of active alerts. Chainfolio automatically optimizes battery usage by batching evaluations.
Alert Triggering Too Frequently
Solution: Increase cooldown periods or adjust thresholds. Use "only alert once per X hours" setting for conditions that might fluctuate around thresholds.
Technical Implementation Notes
- Local‑Only Evaluation – All alert logic runs on your device, no server calls
- Encrypted Storage – Alert configurations stored in encrypted local database
- Deterministic Results – Same data produces same alerts across devices
- Graceful Degradation – If background processing unavailable, alerts evaluate on next app open
- Privacy‑Preserving – Alert conditions never leave your device, even when notifications fire