apprise-transactions: A Python repository from apprises

ap·prise / verb
To inform or tell (someone). To make one aware of something.

Apprise Transactions aims to enable push Notifications for Monero for just about every notification service

notification services available to us today such as: Telegram, Discord, Slack, Amazon SNS, Gotify, etc.

One notification library to rule them all.
A common and intuitive notification syntax.
Supports the handling of images and attachments (to the notification services that will accept them).

Use Cases

Community funding initiatives: XMRArtFund Twitter

Twitch Stream Donation Alerts: Twitch user itey58 Streamlabs

Push notifications to Group Chat: Donations Demo Telegram

No Monero wallet exists that supports notification on incoming transactions, you can setup Pushbullet for you to receive notifications on Mobile or desktop via the Pushbullet or Growl integration

Supported Notifications

This project is dependent on Apprise for notifications.

Please see the official Apprise wiki for a full list of services that are supported.

Supported Payment Platforms

The table below identifies the platforms this tool supports and some example service urls you need to use in order to take advantage of it. Click on any of the services listed below to get more details on how you can configure Apprise to access them.

Payment Platform	Status	Dependent Services	Default Port
Monero	Implemented (Stable)	monerod / monero-wallet-rpc	(TCP) 18081 / (TCP) 18082
Bitcoin	Pull Request wanted	Bitcoin	TBD

Installation

The easiest way is to install this package is from pypi:

pip install apprise-transactions

Command Line

A small command line tool is also provided with this package called apprise-transactions. If you know the server url's you wish to notify, you can simply provide them all on the command line and send your notifications that way:

Note: The command line tool is intended to be executed once per transaction.

# Here is a full example, but we will go over the parts of the command below

monero-wallet-rpc --wallet-file ~/mywallet --rpc-login user:password --rpc-bind-port 18088 --prompt-for-password \
--tx-notify "/usr/bin/apprisetransactions --payment_provider Monero --tx_id %s \
--urls tgram://1034520651:CCCFjiawu448agga4TI_Bu3oolct1Qrxasdjf --debug --get_tx_details \
-s 0 -b You%20have%20received%20%7Bamount%7D%20%7Bcurrency%7D%2C%20which%20is%20currently%20worth%20%24%7Bamount_in_usd%7D \
-t Congrats%20incoming%20payment%20from%20%7Bpayment_provider%7D"

# First you should test that notifications are working with your preferred notification service(s) with the basic command line parameters, then add additional parameters
apprisetransactions --payment_provider Monero --tx_id testsdiajetestasjdftestasdjf --urls tgram://1043520651:CCCFjiawu448agga4TI_Bu3oolct1Qrxasdjf

# To have automated notifications when receiving a new transaction you need to run a command that kicks off this tool while passing the tx_id
# --detach should be added if this process should run in the background
monero-wallet-rpc --tx-notify ""

# The full path of apprisetransacttions needs to be specified within the tx-notify parameter for it to be executed
# find and note the static path
# linux
which apprisetransactions
# example output: /usr/bin/apprisetransactions
# we now add this to our previous command, with %s being passed to the tx_parameter

monero-wallet-rpc --tx-notify "/usr/bin/apprisetransactions  --payment_provider Monero \
--tx_id %s --urls tgram://1043520651:CCCFjiawu448agga4TI_Bu3oolct1Qrxasdjf"

# Specify a username and password for --rpc-login in order to pull the transaction details from the monero-wallet-rpc
# The username and password you specify for the --rpc-login parameter also needs to be specified in the server config
# Modify the [example config](https://github.com/apprises/apprise-transactions/blob/master/example_server.cfg) with your rpc information
# Using the --server_config parameter specify the location of the configuration file
monero-wallet-rpc --tx-notify "/usr/bin/apprisetransactions  --payment_provider Monero \
--tx_id %s --urls tgram://1043520651:CCCFjiawu448agga4TI_Bu3oolct1Qrxasdjf" --server_config /etc/apprise/server.cfg

# Now let's look at examples of all the parameters one can use with apprisetransactions

# Send a notification to as many servers as you want
# as you can easily chain one after another:
monero-wallet-rpc --tx-notify "/usr/bin/apprisetransactions \
--payment_provider Monero --tx_id %s \
--urls mailto://userid:password@example.com?smtp=mail.example.com&from=noreply@example.com&name=no%20reply,pbul://o.gn5kj6nfhv736I7jC3cj3QLRiyhgl98b"

# If you don't specify a --body (-b) or --title (-t) then the default is taken
# --title Received%20transaction%20from%20%7Bpayment_provider%7D
# resolves to "Received transaction from Monero"
# --body Check%20your%20wallet%20for%20more%20details
# resolves to "Check your wallet for more details"
# Go to https://www.urlencoder.org/ for easy url encoding
# Another example below: You have received {amount} {currency}, which is currently worth ${amount_in_usd}
monero-wallet-rpc --tx-notify "/usr/bin/apprisetransactions \
--payment_provider Monero --tx_id %s \
--urls mailto://userid:password@example.com?smtp=mail.example.com&from=noreply@example.com&name=no%20reply \
--get_tx_details \
--body You%20have%20received%20%7Bamount%7D%20%7Bcurrency%7D%2C%20which%20is%20currently%20worth%20%24%7Bamount_in_usd%7D"

# By default only the fact that you received a transaction is conveyed
# --get_tx_details needs to be specified if you want to utilize the following placeholders:
# {amount} {fee} {note} {recipient} {timestamp} {confirmations}
monero-wallet-rpc --tx-notify "/usr/bin/apprisetransactions \
--payment_provider Monero --tx_id %s \
--urls mailto://userid:password@example.com?smtp=mail.example.com&from=noreply@example.com&name=no%20reply \
--get_tx_details \
--body {recipient}"

#  For developers who want to forward the raw data to another server can do so
# Just specify --get_tx_details and --get_raw_data
# XML / JSON directly to a port or via Amazon SNS is supported
# body / title parameters will be ignored
monero-wallet-rpc --tx-notify "/usr/bin/apprisetransactions \
--payment_provider Monero --tx_id %s \
--urls json://user:password@hostname:port \
--get_tx_details \
--get_raw_data"

# By default transactions are notified by the configured server immediately
# For higher security specify the number of confirmations as a parameter
# -1 will notify both, when the transaction is found in the mem pool and when the transaction is added to a block
# 0 is the default
# 1 means that the transaction has been added to one block on the network
# The example below is 10, meaning 10 nodes in the network must have accepted your tx in their next block
monero-wallet-rpc --tx-notify "/usr/bin/apprisetransactions  --payment_provider Monero \
--tx_id %s --urls tgram://1043520651:CCCFjiawu448agga4TI_Bu3oolct1Qrxasdjf \
--security_level 10"

Configuration

To request further transaction details requests are made to a server. The server configuration must be configured when --get_tx_details is passed.

Optionally server configuration can be stored in a file.

# Configuration files can be stored anywhere and passed in via --server_config (-c)
monero-wallet-cli --tx-notify "/usr/bin/apprisetransactions \
--payment_provider Monero --tx_id %s \
--urls pbul://o.gn5kj6nfhv736I7jC3cj3QLRiyhgl98b \
--server_config /etc/apprise/server.cfg"

Attaching Files

Apprise also supports file attachments too! Specify as many attachments to a notification as you want.

# Include a custom image in the notification:
monero-wallet-rpc --tx-notify "/usr/bin/apprisetransactions \
--payment_provider Monero --tx_id %s \
--urls discord:///4174216298/JHMHI8qBe7bk2ZwO5U711o3dV_js \
-attach https://siasky.net/fAOAieEJvZ0FegbcZMPWAtbKKscdUKXCimkjtv6uHKW9-A"

Developers

To send a notification from within your python application, just do the following:

# import one or more of the transaction factories
from apprisetransactions.factories import MoneroFactory
# import one or more transaction types
from apprisetransactions.transactions import MoneroTransaction
# import server config that's needed to get the details of a transaction
from apprisetransactions.configuration import ServerConfig
# import security settings
from apprisetransactions import settings
from apprisetransactions.settings import BlockchainSecurity
# initialize singletons
settings.init()
# set your security level
settings.security_level = BlockchainSecurity.IN_A_BLOCK
# Create a transaction factory
transaction_factory = MoneroFactory(server_config_file='server.cfg')
# Get a transaction from the transaction factory
transaction: MoneroTransaction = transaction_factory.get_transaction(
            tx_id='asdf',
            get_tx_data=True,
            get_raw_data=True,
        )
# specify the notification services that you want to use in a list
urls = ['pbul://o.gn5kj6nfhv736I7jC3cj3QLRiyhgl98b']
body = 'Transaction received: {tx_id}'
title = 'Transaction incoming from {payment_provider}'
attach = 'https://siasky.net/fAOAieEJvZ0FegbcZMPWAtbKKscdUKXCimkjtv6uHKW9-A'
# Have the notification services propagate the transaction notification
# A sample pushbullet notification:
apprise_result = transaction.notify(
    urls=urls, body=body, title=title, attach=attach
)
if apprise_result is False:
    logging.error('Apprise failed to complete notification')

Attaching Files

Attachments are very easy to send using the API:

apprise_result = transaction.notify(
    urls=urls, body=body, title=title, attach='/local/path/to/my/DSC_003.jpg'
)

To send more than one attachment, you just need the AppriseAttachment object:

from apprise import AppriseAttachment

# Initialize our attachment object
attachments = AppriseAttachment()

# Now add all of the entries we're intrested in:
# ?name= allows us to rename the actual jpeg as found on the site
# to be another name when sent to our receipient(s)
attachments.add('https://i.redd.it/my2t4d2fx0u31.jpg?name=FlyingToMars.jpg')

# Now add another:
attachments.add('/path/to/funny/joke.gif')

# Send your multiple attachments with a single notify call:
apprise_result = transaction.notify(
    urls=urls, body=body, title=title, attach=attachments
)

Want To Learn More?

Want to add a payment provider?

💡 Contribute to the Apprise Transactions Code Base Want to add a notification service?
💡 Contribute to the Apprise Code Base

If you're interested in reading more about this and other methods on how to customize your own notifications, please check out the following links: