For introduction to and use of ALTcointip bot, see http://www.reddit.com/r/ALTcointip/wiki/index

NEW: See altcointip-chef for Chef-automated installation and configuration of ALTcointip bot.

The following Python libraries are necessary to run ALTcointip bot:

• jinja2 (http://jinja.pocoo.org/)
• pifkoin (https://github.com/dpifke/pifkoin)
• pyvircurex (https://github.com/christopherpoole/pyvircurex)
• praw (https://github.com/praw-dev/praw)
• sqlalchemy (http://www.sqlalchemy.org/)
• yaml (http://pyyaml.org/wiki/PyYAML)

You can install jinja2, praw, sqlalchemy, and yaml using pip (Python Package Index tool) or a package manager in your OS. For pifkoin, you'll need to copy or symlink its "python" subdirectory to "src/pifkoin". For pyvircurex, you'll need to copy or symlink its "vircurex" subdirectory to "src/ctb/pyvircurex".

Create a new MySQL database instance and run included SQL file altcointip.sql to create necessary tables. Create a MySQL user and grant it all privileges on the database. If you don't like to deal with command-line MySQL, use phpMyAdmin.

Download one or more coin daemon executable. Create a configuration file for it in appropriate directory (such as ~/.litecoin/litecoin.conf for Litecoin), specifying rpcuser, rpcpassword, rpcport, and server=1, then start the daemon. It will take some time for the daemon to download the blockchain, after which you should verify that it's accepting commands (such as getinfo).

You should create a dedicated Reddit account for your bot. Initially, Reddit will ask for CAPTCHA input when bot posts a comment or message. To remove CAPTCHA requirement, the bot account needs to accumulate positive karma.

Rename or copy included src/sample-config.yml to src/config.yml and configure necessary settings. Configure at least one type of cryptocoin in cc section.

Most configuration options are self-explanatory, the ones that are not are explained below.

• reddit.scan.my-subreddits: If true, scan subscribed subreddits for new comments (not recommended).
• reddit.scan.these-subreddits: If specified, scan given subreddits for comments (not recommended).
• reddit.scan.ignore-subreddits: If specified, ignore given subreddits (when these-subreddits is specified) - Reddit Gold required.

Note: Setting reddit.scan.my-subreddits to false and not specifying reddit.scan.these-subreddits will result in ALTcointip bot checking its inbox only. In such case the bot will rely on the Reddit Gold "mention" feature, where users "mention" bot's username when tipping (such as +/u/mybotuser 1 ltc). Reddit "mention" feature is the most reliable way to operate ALTcointip bot.

• misc.subtract-txfee: If true, network transaction fee is subtracted from the amount specified (when required). Otherwise, it is added to the amount specified. If you'd like to disable transaction fees (not recommended), set cc.COIN.txfee setting to 0.0 for particular COIN.

• regex.keywords: Regular expressions that are used to recognize commands like tipping, info, and withdrawing. Make sure that your tipping keywords are unique on Reddit, otherwise it will conflict with other tip bots.

• kw: Here you can define keywords that can be used in place of amount. You can specify a float value, or a string of Python code that will be executed (from within CtbAction::__init()__) to determine the value. The string of Python code should return a float. Don't forget to update regex.amount.keyword when you make changes to kw.

• logging: Provide INFO-level and DEBUG-level filename to which ALTcointip bot will log its activity. On Unix/Linux, you can use tail -f filename.log to monitor the log file.

• fiat: Fiat (such as USD) parameters are defined here. At the very least, fiat.usd is required.

• cc: Each cryptocoin (such as Litecoin) parameters are defined here. At least one cryptocoin needs to be configured. A few cryptocoin configurations are provided (but disabled) for your convenience. Set cc.COIN.enabled to true to enable particular cryptocoin.

Note: You can see that ALTcointip is relying on coin daemon configuration file in order to connect to coin daemon. For example, cc.ltc.conf-file provides the location of Litecoin coin daemon configuration file. The following settings should be specified in the coin daemon configuration file:

• rpcuser
• rpcpassword
• rpcport
• server=1

• cc.COIN.minconf: Minimum number of network confirmations required before balance is available. "givetip" is non-network transaction, so the setting is set to 1, while "withdraw" is a network transaction, so the setting is set to a higher value.

• cc.COIN.walletpassphrase: For coin daemons that support wallet encryption, you can encrypt the wallet and specify encryption password using this setting. ALTcointip bot will only unlock the wallet when performing a network transaction (such as "withdraw").

1. Ensure MySQL is running and accepting connections given configured username/password
2. Ensure each configured coin daemon is running and responding to commands
3. Ensure Reddit authenticates configured user. Note that from new users Reddit will require CAPTCHA responses when posting and sending messages. You will be able to type in CAPTCHA responses.
4. Execute python _run.py from src directory. The command will not return for as long as the bot is running.
5. Monitor configured INFO-level or DEBUG-level log file wth tail -f filename.log where filename.log is the log file name you've configured (on Unix/Linux).

Here's the first few lines of INFO-level log after successful initialization:

INFO 2013-06-19 06:51:12,216 CointipBot::_init_logging(): -------------------- logging initialized --------------------
INFO 2013-06-19 06:51:12,217 Logging level INFO to ctb-info.log
INFO 2013-06-19 06:51:12,417 Connected to database
INFO 2013-06-19 06:51:12,418 Connected to Peercoin
INFO 2013-06-19 06:51:12,418 Setting tx fee of 0.010000
INFO 2013-06-19 06:51:12,421 Connected to Litecoin
INFO 2013-06-19 06:51:12,421 Setting tx fee of 0.010000
INFO 2013-06-19 06:51:12,423 Connected to Novacoin
INFO 2013-06-19 06:51:12,423 Setting tx fee of 0.010000
INFO 2013-06-19 06:51:12,426 Connected to Namecoin
INFO 2013-06-19 06:51:12,426 Setting tx fee of 0.010000
INFO 2013-06-19 06:51:12,428 Connected to Terracoin
INFO 2013-06-19 06:51:12,428 Setting tx fee of 0.010000
INFO 2013-06-19 06:51:12,430 Connected to Devcoin
INFO 2013-06-19 06:51:12,431 Setting tx fee of 1.000000
INFO 2013-06-19 06:51:15,132 Logged in to Reddit
INFO 2013-06-19 06:51:25,492 < CointipBot::__init__(): DONE, batch-limit = 99999, sleep-seconds = 30

Backups are very important! The last thing you want is losing user wallets or record of transactions in the databse.

There are two simple backup scripts included (src/_backup_db.py and src/_backup_wallets.py) that support backup to local directory and (optionally) to a remote host with rsync. Here's a crontab crontab entry scheduling a backup every 15 minutes to a local directory ~/backups as well as to remote server my-server-1.example.com:backups/:

*/15    *       *       *       *       cd ~/git/altcointip/src && python _backup_db.py ~/backups my-server-1.example.com:backups/ && python _backup_wallets.py ~/backups my-server-1.example.com:backups/

Make sure to create all destination directories, and test whether backup is actually being performed.

If you want to add a new cryptocoin after you already have a few registered users, you need to retroactively create the new cryptocoin address for users who have already registered. See src/_add_coin.py for details on how to do that.