WLOX - Open Source Cryptocurrency Exchange

WLOX is an open source cryptocurrency exchange that supports multiple fiat currencies.

At this point, the exchange only supports one cryptocurrency at a time. We plan to adapt the project to a multiple-crypto-currency environment soon.

WLOX is configured to use Crypto Capital Corporation as the default banking services provider. For more information about them, please visit http://www.cryptocapital.co.

The purpose of this document is to walk you throught the process of a typical setup of the app using a bitcoind server.

IF YOU INSTALLED WLOX PRIOR TO 14/01/2015, PLEASE READ THE FILE UPDATE_GUIDE_v1.04 BEFORE CONTINUING

Getting Started

WLOX runs on the traditional PHP/MySQL/Apache setup.

For a development environment, you can simply clone the whole set of WLOX repositories by doing git clone --recursive https://github.com/wlox/wlox.git.

For a production environment, it is strongly recommended to distribute the different repositories across multiple servers. You can clone each sub-module independently by doing https://github.com/wlox/wlox-[submodule].git.

Project Structure

WLOX is structured as one main git repository with multiple sub-modules. As mentioned above, you can clone the whole project or each repository on it's own.

• wlox > The master repo. DB updates and documentation reside here.
• |-- wlox-frontend > The App's frontend.
• |-- wlox-auth > Handles user authentication.
• |-- wlox-api > Handles all requests for data made by the frontend.
• |-- wlox-cron > Contains all cron jobs.
• |-- backstage2 > The CMS (back end) program.

Requirements

• PHP/MySQL/Apache (see section called PHP Configuration below).
• bitcoind server, running as daemon (see section called bitcoind configuration below).
• Warm Wallet: A secure Bitcoin wallet that is not connected to WLOX. WLOX will send a percentage of Bitcoin deposits to this address automatically. This is normally a half-way point between the Hot Wallet (bitcoind) and cold storage. See the Warm Wallet section below.
• Cold Storage: We recommend using some kind of cold storage for your Bitcoin reserves, such as a hardware wallet and an actual safe deposit box in a bank or other safe place.

Initializing the Database

To set up the database, the first step is to create an empty database on your MySQL database server. Then, create a user with the following priviledges: SELECT, INSERT, UPDATE and DELETE.

You will find a file called wlox.sql.gz in the main project directory. Import this file into the database that you have created.

Setting up the Back-End (backstage2)

As mentioned above, WLOX comes with its own administrative program, backstage2, which is really a seperate project developed over a few years.

You can clone backstage2 doing git clone https://github.com/wlox/backstage2.git. After cloning, rename the file cfg.php.example to cfg.php and define the following variables:

• $CFG->dbhost: The address of the database server.
• $CFG->dbname: The database name.
• $CFG->dbuser: The database username.
• $CFG->dbpass: The password for the database.

You can now log in using user/password admin/admin. You should obviously remove this user in a production setup.

Configuring WLOX to Run

Once you have managed to install and access backstage2, log in using admin/admin and go to 'Status'=>'App Configuration'. This the is the place where you will specify all of the application's settings from now on:

Global App Settings

• Application Timezone: The default timezone of WLOX (the frontend will be seen in each user's timezone).
• BTC Miner's Fee: The fee for sending Bitcoin, collected by the network. We recommend 0.001.
• Currency Conversion Fee (%): A number between 0 and 100 (decimals allowed). The fee collected by WLOX when a trade happens across currencies.
• Exchange's Name: For example 'MyExchange'. Will be used in place of [exchange_name] in site content.
• Fiat Withdrawal Fee: Not implemented. Leave at 0 for now, unless you want to develop this feature!
• Min. Order Amnt. (USD): The minimum order that can be placed.
• Min. Order Price (% under Mkt.): A number between 0 and 100 (decimals allowed). Specifies how far under the last trade price a Bid order can be placed.
• **Password Hash Key: A salt Used by mcrypt for hashing user passwords in the DB.
• Password Permitted Regex: REGEX that specifies password character set.
• Password Min. Chars.: The minimum length for user passwords.
• Enable Cross-Currency Trades: Disable if you want each currency to have a seperate order book.
• Notify when a new user registers: By email.
• Notify user fiat withdrawals: By email.

Email Settings

• Support Email: The email address you will use for user support.
• Contact Form Email: The email address for the site's contact form.
• Sender's Name: System emails will be sent by this name.
• SMTP Host: Ex. smtp.myserver.com
• SMTP Port: Ex. 465
• SMTP Security Type: Ex. ssl
• SMTP Username: For SMTP mail account.
• SMTP Password: For SMTP mail account.
• SMTP Sender Email: Can be the same as support email above.

Bitcoin Server Settings

• Username: The username for bitcoind.
• Account Name: The account name for bitcoind (optional, but makes things neater - can be same as username).
• Passphrase: Use something strong.
• Host: Use the server's IP if you are using multiple servers.
• Port: 8332 by default.
• Protocol: http by default.
• Reserve Min. BTC (for Send to Warm Wal.): 1 by default. The minimum hot wallet balance at which WLOX will send to the warm wallet.
• Reserve Ratio (% in Hot Wallet): A number from 0 to 100. The percentage of BTC reserves that will be kept in the hot wallet.
• Warm Wallet BTC Addr.: BE VERY CAREFUL TO INPUT THE RIGHT ADDRESS! Receiving address for the warm wallet.

Third Party API Keys

• Authy API Key: If you want to use Authy for 2FA (Google 2FA also supported, needs no API key).
• Quandl API Key: Optional. Quandl is a data service that you can use to get historical prices of Bitcoin to populate your price history before you begin generating your own.
• Help Desk API Key: If you use a third-party help desk. Accesible in the code as $CFG->helpdesk_key.

Frontend Config

• Base URL: For example http://mysite.com/.
• Dir Root: The web directory of the repo. For example /var/www/wlox/frontend/htdocs/.

API Config

• DB Debug On Fail: Will halt script and output DB errors to PHP error stream.
• Dir Root: The web directory of the repo. For example /var/www/wlox/api/htdocs/.

Auth Config

• DB Debug On Fail: Will halt script and output DB errors to PHP error stream.

Cron Config

• DB Debug On Fail: Will halt script and output DB errors to PHP error stream.
• Dir Root: The web directory of the repo. For example /var/www/wlox/cron/.

Backstage Config

• DB Debug On Fail: Will halt script and output DB errors to PHP error stream.
• Dir Root: The web directory of the repo. For example /var/www/wlox/backstage2/.

Setting up the API Server

The API server provides a layer of security and abstraction between the frontend server and the database in order to prevent direct communication between these two components.

Install by doing git clone https://github.com/wlox/wlox-api.git in the intended space.

When this is ready, rename cfg/cfg.php.example to cfg/cfg.php and set:

• $CFG->dbhost: The IP or host name of your database server.
• $CFG->dname: The name of the database on that server
• $CFG->dbuser: The database user.
• $CFG->dbpass: The database user's password.

Setting up the Auth Server

The purpose of the Auth server is to allow users to initiate sessions and obtain a session key so that they can access protected methods on the API.

Install by doing git clone https://github.com/wlox/wlox-auth.git in the intended space.

When this is ready, rename cfg.php.example to cfg.php and set:

• $CFG->dbhost: The IP or host name of your database server.
• $CFG->dname: The name of the database on that server
• $CFG->dbuser: The database user.
• $CFG->dbpass: The database user's password.

Setting up Cron Jobs

IMPORTANT: Should run on the same server as bitcoind daemon!

The Cron Jobs necessary for WLOX to run are provided in this repository.

Install by doing git clone https://github.com/wlox/wlox-auth.git in the intended space.

When this is ready, rename cfg.php.example to cfg.php and set:

• $CFG->dbhost: The IP or host name of your database server.
• $CFG->dname: The name of the database on that server
• $CFG->dbuser: The database user.
• $CFG->dbpass: The database user's password.

The next step is to set the right permissions so that these files can be run as cron jobs. This includes setting up the appropriate permissions for the /transactions directory so that the provided receive.sh file can create files in there.

When that is ready, we need to set up each file to be run by the server's cron tab. The cron jobs should be scheduled as follows:

• daily_stats.php - Should run at 0 min, 0 hrs (the very start) of every day.
• get_stats.php - Every 10 minutes.
• maintenance.php - Every 5 minutes.
• monthly_stats.php - 0 min, 0 hrs (the very start) of the first day of every month.
• process_bitcoin.sh - Every minute.

Setting up the Bitcoind Server

Please install bitcoind from the ppa:bitcoin/bitcoin repository.

Then locate a file called bitcoin.conf (u