Push Notifications for Your Self-Hosted Wallet

2026-03-31

Your AI trading bot just lost $10,000 because you were asleep when it tried to make a risky trade that needed your approval. The notification never reached you, buried somewhere in a Slack channel you don't monitor at 3 AM. Sound familiar?

When you're running AI agents with real money on the line, every missed notification could be costly. Whether it's a policy violation that needs your immediate attention, a transaction stuck in approval limbo, or suspicious activity that requires your kill switch, you need bulletproof alerts that actually reach you wherever you are.

The stakes are higher than just missing a message. In the world of automated trading and DeFi, minutes matter. A delayed approval could mean missing a profitable arbitrage opportunity. A missed security alert could mean your agent continues executing trades under compromise. Your financial sovereignty depends on staying connected to your automated systems — but most wallet infrastructure treats notifications as an afterthought.

Why Self-Hosted Notifications Matter

When you're serious about financial privacy and control, sending your transaction data through third-party notification services defeats the purpose of self-hosting in the first place. Every push notification through Apple's or Google's servers potentially exposes metadata about your trading activity, wallet balances, and transaction patterns.

WAIaaS takes a different approach. It's an open-source, self-hosted Wallet-as-a-Service that gives you complete control over how your AI agents handle money — including how they communicate with you. With 611+ test files across all packages, Docker deployment at ghcr.io/minhoyoo-iotrust/waiaas:latest, and a 14-package monorepo architecture, it's built for production self-hosting from day one.

The notification system operates through 3 signing channels: push-relay-signing-channel, telegram-signing-channel, and wallet-notification-channel. This means you can receive critical alerts through multiple channels without relying on centralized services that might log or analyze your financial data.

The Architecture: Your Keys, Your Notifications, Your Rules

WAIaaS implements a 3-layer security model where notifications play a crucial role:

  1. Session auth → AI agents authenticate via JWT
  2. Time delay + approval → Risky transactions get queued for human review
  3. Monitoring + kill switch → Real-time alerts when things go wrong

The 7-stage transaction pipeline ensures you're notified at the right moments. When a transaction hits the policy engine with 21 policy types across 4 security tiers (INSTANT, NOTIFY, DELAY, APPROVAL), the system automatically determines whether you need to be alerted immediately or can review it later.

Here's what a typical notification flow looks like:

# Set up a spending limit policy that triggers notifications
curl -X POST http://127.0.0.1:3100/v1/policies \
  -H "Content-Type: application/json" \
  -H "X-Master-Password: my-secret-password" \
  -d '{
    "walletId": "<wallet-uuid>",
    "type": "SPENDING_LIMIT",
    "rules": {
      "instant_max_usd": 100,
      "notify_max_usd": 500,
      "delay_max_usd": 2000,
      "delay_seconds": 900,
      "daily_limit_usd": 5000
    }
  }'

With this policy active, any transaction between $100-500 executes immediately but sends you a notification. Transactions $500-2000 get delayed for 15 minutes (giving you time to cancel), while anything above $2000 requires your explicit approval through WalletConnect integration or Telegram.

The beauty of self-hosting is customization. You can modify the notification thresholds, add custom webhook endpoints, or integrate with your existing monitoring stack — all without asking permission from a SaaS provider.

Docker Deployment: Notifications in Minutes

Getting started with self-hosted wallet notifications is surprisingly straightforward. The Docker deployment with auto-provision, Docker Secrets, healthcheck, and non-root execution (UID 1001) means you can have a production-ready setup in one command:

# Clone and start — notifications included
git clone https://github.com/minhoyoo-iotrust/WAIaaS.git
cd WAIaaS
docker compose up -d

The Docker image includes a push-relay service for mobile notifications that doesn't route through Apple or Google's servers. Your notification infrastructure runs entirely on your hardware.

For production deployments, you can use Docker Secrets to secure your configuration:

# Create notification credentials
mkdir -p secrets
echo "your-telegram-bot-token" > secrets/telegram_token.txt
echo "your-push-endpoint" > secrets/push_endpoint.txt
chmod 600 secrets/*.txt

# Deploy with secrets overlay
docker compose -f docker-compose.yml -f docker-compose.secrets.yml up -d

The system binds to 127.0.0.1:3100:3100 by default, keeping your API private while allowing you to expose only specific notification endpoints to the internet if needed.

Multi-Channel Notifications That Actually Work

Unlike simple webhook systems, WAIaaS notifications are context-aware and actionable. When your AI agent triggers a policy violation, you don't just get a generic alert — you get the specific transaction details, the policy that was violated, and direct links to approve or deny the action.

The CLI provides 20 commands for managing your notification setup:

waiaas notification setup    # Configure Telegram, push relay, or custom webhooks
waiaas owner connect        # Link your wallet for transaction approvals
waiaas owner status         # Check notification channel health

Here's how you might configure multiple notification channels for redundancy:

# Set up Telegram notifications
waiaas notification setup --type telegram --token <bot-token> --chat-id <your-chat-id>

# Add push notifications for mobile
waiaas notification setup --type push-relay --endpoint <your-endpoint>

# Configure email fallback
waiaas notification setup --type webhook --url <your-email-webhook>

The system automatically handles failover between channels. If your primary notification method fails, alerts get routed to your backup channels without manual intervention.

Integration with AI Agent Frameworks

The real power emerges when you integrate with AI frameworks. WAIaaS provides 45 MCP tools for AI agent integration, including notification management tools that let your agents understand and respond to approval workflows.

{
  "mcpServers": {
    "waiaas": {
      "command": "npx",
      "args": ["-y", "@waiaas/mcp"],
      "env": {
        "WAIAAS_BASE_URL": "http://127.0.0.1:3100",
        "WAIAAS_SESSION_TOKEN": "wai_sess_<your-token>",
        "WAIAAS_DATA_DIR": "~/.waiaas"
      }
    }
  }
}

With this setup, your AI agent can not only execute trades but also communicate the status back to you through your preferred notification channels. Claude can tell you: "I found a profitable arbitrage opportunity worth $1,200, but it exceeds your $500 notify threshold. I've submitted it for approval and sent you a Telegram notification. Would you like me to explain the trade details while we wait?"

TypeScript SDK for Custom Notification Logic

For developers who want to build custom notification workflows, the TypeScript SDK provides the building blocks:

import { WAIaaSClient } from '@waiaas/sdk';

const client = new WAIaaSClient({
  baseUrl: 'http://127.0.0.1:3100',
  sessionToken: process.env.WAIAAS_SESSION_TOKEN,
});

// Monitor transaction status with custom notifications
async function monitorTransaction(txId: string) {
  while (true) {
    const tx = await client.getTransaction(txId);
    
    if (tx.status === 'PENDING_APPROVAL') {
      // Custom notification logic here
      await sendSlackAlert(`Transaction ${txId} needs approval: ${tx.amount} ${tx.symbol}`);
      break;
    }
    
    if (tx.status === 'COMPLETED') {
      await sendSlackAlert(`✅ Transaction confirmed: ${tx.txHash}`);
      break;
    }
    
    await new Promise(resolve => setTimeout(resolve, 5000));
  }
}

The SDK includes zero external dependencies, making it suitable for serverless functions, edge computing, or embedded devices that need to monitor wallet activity.

Privacy-First Architecture

Self-hosting your notification infrastructure means your trading patterns stay private. When you're running strategies that involve significant capital or proprietary signals, the last thing you want is notification metadata flowing through third-party services that might analyze or store your activity patterns.

WAIaaS notifications are designed around this principle. The push-relay service runs alongside your wallet daemon, creating an encrypted channel between your infrastructure and your devices. Transaction amounts, recipient addresses, and timing patterns never leave your server unless you explicitly configure external webhooks.

The system also supports ERC-8128 HTTP signing domains for authenticated API calls, meaning your notifications can include verifiable proof that they originated from your wallet infrastructure rather than a spoofed source.

Getting Started with Self-Hosted Wallet Notifications

Ready to take control of your AI agent notifications? Here's how to get started:

  1. Deploy WAIaaS with Docker: git clone https://github.com/minhoyoo-iotrust/WAIaaS.git && cd WAIaaS && docker compose up -d

  2. Set up your first wallet: waiaas quickset --mode mainnet (creates wallets and sessions automatically)

  3. Configure notifications: waiaas notification setup and follow the prompts for your preferred channels

  4. Create policies with notification triggers: Use the policy API to set spending limits that generate alerts

  5. Connect your AI agent: Add the MCP integration to Claude Desktop or use the TypeScript/Python SDKs for custom frameworks

Your self-hosted wallet infrastructure is now monitoring your AI agents and keeping you informed through channels you control. No third-party custody, no external dependencies for critical alerts, and complete visibility into your automated trading systems.

The combination of financial sovereignty and reliable notifications creates a foundation for serious AI agent deployments. You maintain custody of your keys while staying connected to your automated systems through infrastructure you control.

Ready to deploy your own wallet notification infrastructure? Check out the complete documentation and deployment guides at https://waiaas.ai, or dive into the source code at https://github.com/minhoyoo-iotrust/WAIaaS.