burst-balance-alert

Simple service, that notifies you (or others) via Mail, SMS, Discord, or Telegram, when a Burst account reaches a certain balance.

Mail is not supported yet

Introduction

Sometimes it is important (or just interesting) when a certain Burst account reaches a specific value. This little service allows you to check for such a condition. It is built as a tiny serverless (lambda) function, that can be called via a simple Http request. If the desired condition is met (see below), a message will be sent according the passed arguments, i.e. as SMS, Mail, or Telegram message.

In combination with a periodic check (e.g. every hour), you can monitor an account's balance, e.g.to keep an eye on it. I use this service to monitor the Burst Activator Account using Uptime Robot

All for free

Keep in mind, that this solution is somehow scalable as AWS, Zeit Now is used, but this might involve incalculable costs. For personal use, you can easily monitor several dozen accounts every 5 Minutes for free, using free tiers of AWS (100 SMS/month free), Zeit Now, and/or Uptime Robot or Freshping

Usage

Once the service is up (see chapter Installation) you can call it using Http GET (e.g. possible to call in browser)

Authentication

Some endpoints are protected to avoid spamming and though uncontrolled costs (mainly for AWS send services). It uses Basic Authentication, for which username and password are configured during setup (API_USER and API_PASS). So, the Authorization Header must be set (or in Browser you'll be asked for credentials)

Example

This is how a request with curl may look like

curl --location --request GET 'localhost:3000/api/check-balance?account=13736966403016142704&compare=lt&targetBurst=10&msgRecipient=discord:1234567890981733/cVoNiUCPmHZgqXa85tJBQf8vzyWiwrcR6S7xBHefHrYbiR9-6vPR9Uzgz3X5wkYNroT_&msgRecipient=telegram:2a3137d2-2d6a-4e4d-985a-df0d278426b09&msgRecipient=sms:+5511912345678&alias=MyAccount' \
--header 'Authorization: Basic U29tZVRlc3RVc2VyOlNvbWVUZXN0VXNlclBhc3M='

Endpoints

Health Check

No Auth required

/api/status - returns 200 and a message

Balance Check

Needs Authentication

/api/check-balance?<params>

with following Params

Argument	Description	Required
account	The accounts id	required
alias	An arbitrary alias for the account (max. 20 chars)	optional
compare	The comparison operator: lt or gt	optional
targetBurst	The balance target for comparison in BURST	required, if `compare`
msgRecipient	A tuple in form `type:address` for notification. Type must be one of sms, mail, discord, or telegram	required, if `compare`

Example

Just returns an account's balance, without any notification

/api/check-balance?account=13736966403016142704

Returns:

{
    "account": "13736966403016142704",
    "balanceBurst": "16928.87210584",
    "notified": false
}

Checks for an account's balance, and if less than 10 BURST sends an SMS to given phone number

/api/check-balance?account=13736966403016142704&compare=lt&targetBurst=10&msgRecipient=sms:+5511912345678

Returns something like this:

{
    "account": "13736966403016142704",
    "balanceBurst": "8.34955",
    "targetBurst": "10",
    "comparator": "lt",
    "notified": true,
    "hasNotificationError": false
}

To send to multiple channels just add another msgRecipient parameter.

/api/check-balance?account=13736966403016142704&compare=lt&targetBurst=10&msgRecipient=sms:+5511912345678&msgRecipient=telegram:2a3137d2-2d6a-4e4d-985a-df0d278426b0

Installation

To run the service, some preparations are necessary, as this service uses AWS SNS and is built for Zeit Now (although, should be possible to host on other PaaS, like Heroku or Netlify, but you'll probably need to some platform specific routing)

Install Prerequisites

Install NodeJS 13+
Create an AWS Account (if you want to support SMS)
Create a Zeit Now Account
Clone this repo (requires git): git clone https://github.com/ohager/burst-balance-alert.git
Run npm i (to install all dependencies)

Setup Zeit Now

Once you have created an account you need to configure several access keys, i.e. for AWS, also the Basic Authentication for the service itself. The keys will be provided as environment variables, such that they can be injected securely.

The following variables need to be set:

API_USER=<Username for Basic Auth>
API_PASS=<Password for Basic Auth>
AWS_KEY_ID=<Amazon AWS key id>
AWS_SECRET_KEY=<Amazon AWS secret>
# Keep the peer address as it is, and change if you know what you are doing
BURST_PEER=https://wallet.burst-alliance.org:8125 
# The explorer used for linking in messages
BURST_EXPLORER=https://explorer.burstcoin.network

Local Setup

For local development it's sufficient to copy .env.example to .env and set the variables accordingly.

Run Locally

Once set you can run the service locally by just call npm run start:dev Your service should be available on localhost:3000. To check if service is up copy the following line into your browser:

http://localhost:3000/api/status

If all is fine, you will see a message like: Burst Balance Alert is up

Production Setup

For deployment on Zeit you need to run the following commands to securely configure your sensitive variable values.

now secrets add burst-balance-alert-user <your username>

now secrets add burst-balance-alert-pass <your password>

now secrets add aws-key-id <your aws key id> (see chapter "SMS Notification")

now secrets add aws-secret-key <your aws secret> (see chapter "SMS Notification")

Deploy

Once set you can deploy the service by calling npm run deploy Your service will be deployed to Zeit Now and will be available under the returned Urls, e.g. burst-balance-alert.<username>.now.sh

To check if service is up copy the following line into your browser:

http://<zeit-url>/api/status

If all is fine, you will see a message like: Burst Balance Alert is up

SMS Notification

To send SMS you'll need to have an Amazon AWS account (The free tier is more than sufficient). I recommend not to use your root keys, but create a specific user with limited permissions. Therefore, you go to the AWS IAM Console

Create a Group and select the following permissions
- AmazonSESFullAccess
- AmazonSNSFullAccess
Create A User and add him to the created group
Select the User, go to the Security Credentials setup, and create an Access Key
Write down the id and key; you'll need to inject these credentials as environment variables AWS_ID and AWS_SECRET

🚨 KEEP THIS KEY SECRET 🚨

Telegram Notification

To deliver messages on telegram the Middleman-Bot is used. You just need to add the bot in your Telegram messenger, and you'll receive an id (e.g. 2a3137d2-2d6a-4e4d-985a-df0d278426b0). This id should be used for the msgAddress parameter.