Push Notifications Setup

FreqDroid delivers push notifications when your bots open or close trades using ntfy — a self-hosted notification server. Your trading data never touches a third-party service.

How it works

FreqTrade publishes messages to your ntfy server via webhooks. FreqDroid subscribes to the same topics and displays native OS notifications.

FreqTrade bot  →  POST  →  ntfy server  →  stream  →  FreqDroid  →  notification

Step 1 — Run an ntfy server

You can use the public ntfy.sh server for testing, but for production use with trading data a self-hosted instance is strongly recommended.

Docker (recommended)

docker run -p 80:80 -v /var/cache/ntfy:/var/cache/ntfy binwiederhier/ntfy serve

docker-compose

services:
  ntfy:
    image: binwiederhier/ntfy
    command: serve
    ports:
      - "80:80"
    volumes:
      - ntfy-cache:/var/cache/ntfy
volumes:
  ntfy-cache:

Put this behind a reverse proxy (nginx, Caddy, Traefik) with TLS so the URL is https://ntfy.example.com. HTTPS is required for notifications to work reliably on Android 9+ and iOS.

See the ntfy self-hosting docs for full configuration options.

Step 2 — Note your topic names

FreqDroid derives a topic name for each bot automatically:

topic = "freqdroid-" + botName.lowercase()
                               .replace(' ', '-')
                               .filter { alphanumeric or '-' }

The Settings screen shows the computed topic as a hint.

Step 3 — Configure FreqTrade webhooks

In your FreqTrade config.json, add a webhook section that POSTs to your ntfy topic. Use "format": "raw" so FreqTrade sends plain text.

Important: Include #{trade_id} in your messages. FreqDroid looks for #<number> in the notification text to enable tap-to-navigate — tapping opens the trade detail screen directly.

"webhook": {
    "enabled": true,
    "url": "https://ntfy.example.com/freqdroid-mybot",
    "format": "raw",
    "entry_fill": {
        "data": "Trade opened (#{trade_id})\n{pair} @ {open_rate:.6f} | stake {stake_amount:.2f} {stake_currency}"
    },
    "exit_fill": {
        "data": "Trade closed (#{trade_id})\n{pair} | profit {profit_amount:.2f} {stake_currency} ({profit_ratio:.2%})"
    },
    "entry_cancel": {
        "data": "Entry cancelled (#{trade_id})\n{pair} entry order cancelled"
    },
    "exit_cancel": {
        "data": "Exit cancelled (#{trade_id})\n{pair} exit order cancelled"
    },
    "status": {
        "data": "Status: {status}"
    }
}

Restart FreqTrade after editing config.json. Test the connection with:

curl -d "Test message (#1)" https://ntfy.example.com/freqdroid-mybot

Step 4 — Enable notifications in FreqDroid

1. Open the app, tap the hamburger menu, then Settings
2. Under Notifications, toggle Enable ntfy notifications on
3. Enter your ntfy server base URL (e.g. https://ntfy.example.com) — no trailing slash, no topic name
4. If your server requires Basic Auth, enter Username and Password
5. On Android 13+, grant the notification permission when prompted
6. Choose a delivery mode

Delivery modes (Android)

• Live — maintains a persistent streaming connection via a foreground service. Notifications arrive instantly, but a small persistent notification is shown while the service runs.
• Scheduled — uses WorkManager to poll ntfy at a chosen interval (15 min, 30 min, 1 h, 2 h, etc.). No persistent notification, but trade alerts may be delayed up to the polling interval.

Delivery on iOS

iOS uses BGAppRefreshTask to poll ntfy in the background at the configured interval. iOS controls exact timing — the interval is a minimum, not a guarantee. The app also polls when it comes to the foreground.

Troubleshooting

No notifications arriving

• Confirm FreqTrade is posting to the right URL: POST https://ntfy.example.com/freqdroid-<botname>
• Check the derived topic name matches exactly — special characters and capital letters are stripped/lowercased
• On Android, verify notification permission is granted in system settings
• On iOS, verify permission was granted when first prompted

Tapping a notification doesn’t open the trade

The notification message must contain #<trade_id> (e.g. (#123)). Make sure your webhook templates include #{trade_id} — see Step 3.

Notifications stop after a while (Live mode)

The app maintains a long-lived HTTP streaming connection. If the server closes the connection, the app automatically reconnects with exponential back-off (2 s up to 60 s). No action needed.

ntfy requires authentication

Enter your credentials in the Username and Password fields below the server URL. The app sends a Basic auth header when both fields are non-empty. ntfy access tokens are not supported — use a dedicated ntfy user with a password.