The aim of this tutorial is to show how to connect and communicate with the DevCoin Wallet using the JSON-RPC protocol and PHP. Since DevCoin is a fork of Bitcoin, one can use the API commands for Bitcoins to communicate with the DevCoin Wallet. First, I will show to set up the DevCoin Wallet to accept JSON-RPC communication. Then walk you through using the using the JSON-RPC class with PHP. After which, I will show examples of some API commands for communicating with the DevCoin Wallet. After reading this tutorial one will be able to develop application in PHP to communicate with the DevCoin Wallet.

The first thing one has to do is setup the Devcoin.conf file to accept JSON-RPC protocol. One must create a devcoin.conf and store it at a specific location

1. windows – c:/users/username/AppData/Roaming/devcoin/devcoin.conf
2. linux - ~/.devcoin/devcoin.conf

This file is a configuration file that tells the devcoin wallet how to run. The basic devcoin.conf you will need to run JSON-RPC is listed below

server=1
daemon=1
rpcuser=username
rpcpassword=password
rpcport=6333
port=6334
rpcallowip=127.0.0.1

The server and daemon option must be set to 1 to tell the devcoin wallet to communicate with the JSON-RPC protocol. Rpcuser is the username and rpcpassword is the password needed to connect to the Devcoin Wallet. Port will be set to 6334 and rpcport is set to 6333; these are the ports one connects to communicate with the Devcoin Wallet. Lastly, Rpcallowip tells the Devcoin Wallet which IP address can connect to the wallet. In this example, only the local machine is allowed to connect to the Devcoin Wallet. Note, that the JSON-RPC server of the wallet uses Basic access authentication which can lead one open to people snoopy on your network. To make it more secure one should you SSL to connect to the wallet as it will encrypt the username and password which will help protect against people snoopy for plain text username and password through the basic access authentication. I will not explain how to set up the SSL with the wallet in this tutorial, for now I just want to show you the basic of connecting to and sending API commands to the wallet.

1. JSON stands for JavaScript Object Notation. It allows data to be exchange to and from the client computer and the server.
2. RPC stands for Remote Procedure Call. This allows a computer program to execute a subroutine or procedure on a remote computer
3. JSON-RPC allows a client computer to send/receive data and execute commands on a remote server.

As a programmer one should not reinvent the wheel, and as such there, there is a PHP library already written that handles generic JSON-RPC communication. It can be downloaded at the following website http://jsonrpcphp.org/. There are two version of this library: Full Version and Light Version. The difference is the full version comes with a bunch of examples and references whereas the light version just comes with the two classes needed to communicate with the JSON-RPC protocol. Download the light version for this tutorial. The file that we will be working with is the jsonRPCClient.php.

To include the JSON-RPC class in your PHP script is pretty straight forward just use the require_once command in PHP. After which connect to the JSON-RPC class by passing the class your username, password, host and port. See below to see the code to do this.

require_once('./jsonRPCClient.php');


$dev_connect = array("user" => "username",       // RPC Username
            "pass" =>   "password",              // RPC Password
            "host" =>   "127.0.0.1",             // RPC Hostname/IP
            "port" =>   6333);                   // RPC Port

$mydev = new jsonRPCClient("http://{$dev_connect['user']}:{$dev_connect['pass']}@{$dev_connect['host']}:{$dev_connect['port']}");

The first command just includes the jsonRPCClient class into your php script. The next line just creates an array that contains your username, password, host and port number. The third line initializes an instance of the jsonRPCClient class. There you go; you are connect to the wallet and ready to send API commands

The Devcoin API commands are the same ones that are used with Bitcoin and a full list can be viewed at the following website. https://en.bitcoin.it/wiki/Original_Bitcoin_client/API_Calls_list. We will be going through some of API commands and show PHP examples to demonstrate it usages.

Getbalance [account] – This command will give you the account balance of the account specified. If the account is not given then the Devcoin Wallet will return the total balance of all accounts of your wallet. The below code will demonstrate it usages. In this example I did not specified an account so it is going to give me the total balance of my wallet

<?php
require_once('./jsonRPCClient.php');


$dev_connect = array("user" => "username",       // RPC Username
            "pass" =>   "password",              // RPC Password
            "host" =>   "127.0.0.1",             // RPC Hostname/IP
            "port" =>   6333);                   // RPC Port

$mydev = new jsonRPCClient("http://{$dev_connect['user']}:{$dev_connect['pass']}@{$dev_connect['host']}:{$dev_connect['port']}");
$totalbalance = $mydev->getbalance();
echo “Total Balance of my wallet is $totalbalance”;
?>

getaccount <devcoinaddress> - This will give you the account name for a devcoin address. Add the following code to the bottom of your previous code.

$devaddress = “1L2T5DvEx8cHTkLJTwsexq6Faz4T3sDBnQ” //replace this with your devcoin address
$account = $mydev->getaccount($devaddress);
echo “account name for the devcoin address is $account”;

Note: if $account shows blank, then you probably did not name the label for the address. Go to your Devcoin wallet and click on the address book. Then click on the receiving tab and give your devcoin address a label.

getaccountaddress <account> - This command does just the opposite of the previous command. Given the account name this command will give you the Devcoin address that is associated with the account. To see how this command works add the following code to the bottom of the previous code.

$address = $mydev->getaccountaddress($account);
echo “The Devcoin address associated with $account is $address”;

getnewaddress [account] – It is a good practice to use a different Devcoin address for each transaction. To do this one uses the above command to get a new Devcoin address. The account variable is optional but recommended as it gives the address a label. To see how this works, add the following code.

$newaccount=”secondaccount”;
$newaddress=$mydev->getnewaddress($newaccount);
echo “The new address is $newaddress and has the label $newaccount”;

getreceivedbyaccount [account] – This command returns the total amount received by the account given. If account is not specified than it will return the total amount from all accounts. Example, of this command is given below; add the following code to your PHP script

$amountforaccount=$mydev->getreceivedbyaccount($account);
echo “The total amount for $account is $amountforaccount”;

getreceivebyaddress <devcoin address> - This command is the same as the previous command but it uses address instead of the account. It will return the received balance for a Devcoin address. Note that this command will only show received total and does not take into account any payment that has been send from this address, thus, if you want a true balance of an address one should use the getaddressbalance command. To see this command in action, add the following code.

$amountforaddress=$mydev->getreceivedbyaddress($devaddress);
echo “The total amount for $devaddress is $amountforaddress”;

listaccounts() – this command returns a list of accounts by creating an object with the account names as keys and account balances as values. To see how this works, use the following code.

$accounts=$mydev->listaccounts();
foreach($accounts as $key => $value) {
		echo "$key => $value<br>";
	}

listreceivedbyaddress() – this command will return an array of objects that contain the following • Address – the receiving address • Account – the label of the address • Amount – total amount received by the Devcoin address • Confirmation – number of confirmations received by this Devcoin address Add the following code to see how to use this command.

$receivedaddress=$mydev->listreceivedbyaddress();
foreach($accounts as $value) {
	$address1=$value[‘address’];
	$account1=$value[‘account’];
	$amount1=$value[‘amount’];
	$confirmation1=$value[‘confirmations’];	
	echo "address - $address1<br>";
echo "account - $account1<br>";
echo "amount - $amount1<br>";
echo "confirmations - $confirmation1<br>";
echo "-------------------------------<br>";

}

listtransactions [account][count=10] [from=0] – this command will list the most recent transactions. If [account] is given it will list the most recent transaction of that account. If no [account] is given then it will list the most recent accounts of all account. The [count] option will tell this command to listed [count] number of recent transaction. If [count] is not given then it will default to 10. The [from] option will tell the command to start from a certain position of the listed recent transaction. If [from] is not given then it will default to 0, which means it will start from the most recent transaction. To see how this works add the following code; this will list the most recent transaction from all accounts.

$transactions=$mydev->listtransactions(‘*’,1,0);
$t1=$transactions[0];
	$account=$t1['account'];
	$address=$t1['address'];
	$category=$t1['category'];
	$amount=$t1['amount']*100000000;
	$confirmation=$t1['confirmations'];
	$transactionid=$t1['txid'];
	$confirmation=intval($confirmation);
	echo "confirmation=$confirmation<br>";
	echo "category=$category<br>";
	echo "account=$account<br>";
	echo "address=$address<br>";
	echo "amount=$amount<br>";
	echo "transactionid=$transactionid<br>";

Validateaddress <devcoin address> - this command will return information about the devcoin address. . It will give the following data on a devcoin address

• isvalid – Will be 1 if it is a valid devcoin address or 0 if not a valid devcoin address
• address – The Devcoin address given to this command
• ismine – Will be 1 if the devcoin address is from your wallet or 0 if the devcoin address belongs to another person.
• account – The account name associated with the Devcoin address

Look at the following code for an example.

$devcoininfo=$mydev->validateaddress($devaddress);
echo "validateaddress command<br>";
	$devcoininfo=$mydev->validateaddress($devaddress);
	foreach($devcoininfo as $key => $value) {
		echo "$key - $value<br>";
	}

<?php

require_once('jsonRPCClient.php');


$dev_connect = array("user" => "username",                // RPC Username
            "pass" =>   "password",                       // RPC Password
            "host" =>   "127.0.0.1",                      // RPC Hostname/IP
            "port" =>   6333);                            // RPC Port

	$mydev = new jsonRPCClient("http://{$dev_connect['user']}:{$dev_connect['pass']}@{$dev_connect['host']}:{$dev_connect['port']}");
	
	echo "<h1>Example API calls to the Devcoin Wallet</h1>";
	echo "<hr>";
	echo "<b>getbalance command</b><br>";
	$totalbalance = $mydev->getbalance();
	echo "Total balance of my Wallet is $totalbalance<br>";
	
	echo "<hr>";
	echo "<b>getaccount command</b><br>";
	$devaddress = "1L2T5DvEx8cHTkLJTwsexq6Faz4T3sDBnQ"; //replace this with your devcoin address
	$devaddress1 = "1L2T5DvEx8cHTkLJTwsexq6Faz4T3sDB";
	$devaddress2 = "1L2T5DvEx8cHTkLJTwsexq6Faz4T3sDBn9";
	$account = $mydev->getaccount($devaddress);
	echo "account name for the devcoin address is $account<br>";
	
	echo "<hr>";
	echo "<b>getaccountaddress command</b><br>";
	$address = $mydev->getaccountaddress($account);
	echo "The Devcoin address associated with $account is $address<br>";
	
	echo "<hr>";
	echo "getnewaddress command<br>";
	$newaccount="secondaccount";  //replace this with whatever you want the label to be for the new address
	$newaddress=$mydev->getnewaddress($newaccount);
	echo "The new address is $newaddress and has the label $newaccount<br>";
	
	echo "<hr>";
	echo "<b>getreceivedbyaccount command</b><br>";
	$amountforaccount=$mydev->getreceivedbyaccount($account);
	echo "The total amount for $account is $amountforaccount<br>";
	
	echo "<hr>";
	echo "<b>getreceivedbyaddress command</b><br>";
	$amountforaddress=$mydev->getreceivedbyaddress($devaddress);
	echo "The total amount for $devaddress is $amountforaddress";
	
	echo "<hr>";
	echo "<b>listaccounts command</b><br>";
	$accounts=$mydev->listaccounts();
	foreach($accounts as $key => $value) {
		echo "$key => $value<br>";
	}
	
	echo "<hr>";
	echo "<b>listreceivedaddress command</b><br>";
	$receivedaddress=$mydev->listreceivedbyaddress();
	foreach($receivedaddress as $value) {
		$address1=$value["address"];
		$account1=$value["account"];
		$amount1=$value["amount"];
		$confirmation1=$value["confirmations"];
		echo "address - $address1<br>";
		echo "account - $account1<br>";
		echo "amount - $amount1<br>";
		echo "confirmation - $confirmation1<br>";
		echo "--------------------------------------------------------<br>";
	
	}
	
	echo "<hr>";
	echo "<b>listtransactions command</b><br>";
	$transactions=$mydev->listtransactions('*',1,0);
	$t1=$transactions[0];
	$account=$t1['account'];
	$address=$t1['address'];
	$category=$t1['category'];
	$amount=$t1['amount']*100000000;
	$confirmation=$t1['confirmations'];
	$transactionid=$t1['txid'];
	$confirmation=intval($confirmation);
	echo "confirmation=$confirmation<br>";
	echo "category=$category<br>";
	echo "account=$account<br>";
	echo "address=$address<br>";
	echo "amount=$amount<br>";
	echo "transactionid=$transactionid<br>";
		
	
	echo "<hr>";
	echo "<b>validateaddress command</b><br>";
	$devcoininfo=$mydev->validateaddress($devaddress);
	foreach($devcoininfo as $key => $value) {
		echo "$key - $value<br>";
	}
	
	
?>

The result of the above script should look like the following:

Example API calls to the Devcoin Wallet
________________________________________
getbalance command
Total balance of my Wallet is 50
________________________________________
getaccount command
account name for the devcoin address is Firstaccount
________________________________________
getaccountaddress command
The Devcoin address associated with Firstaccount is 1GAxSmX3cmwtvL823SgjYwPNKputZEcwWs
________________________________________
getnewaddress command
The new address is 18fhx4D7T59548c9PEjTP1ThzwrEXvt6Xb and has the label secondaccount
________________________________________
getreceivedbyaccount command
The total amount for Firstaccount is 30
________________________________________
getreceivedbyaddress command
The total amount for 1L2T5DvEx8cHTkLJTwsexq6Faz4T3sDBnQ is 30
________________________________________
listaccounts command
=> 0
Firstaccount => 30
account1 => 10
secondaccount => 0
test => 0
test1 => 5
test2 => 5
testaccount1 => 0
testaccount2 => 0
________________________________________
listreceivedaddress command
address - 1BDmiFmRR3Nqpb93pm68iUHLvv1zhKpC7u
account - account1
amount - 10
confirmation - 374
--------------------------------------------------------
address - 1Ec8bhnLt47aaG16ryq4t8zmeJc1j7gmsX
account - test1
amount - 5
confirmation - 774
--------------------------------------------------------
address - 1EyusjqAZL68VpgZBDFhCphYm7gDbQcbt5
account - test2
amount - 5
confirmation - 681
--------------------------------------------------------
address - 1L2T5DvEx8cHTkLJTwsexq6Faz4T3sDBnQ
account - Firstaccount
amount - 30
confirmation - 28
--------------------------------------------------------
________________________________________
listtransactions command
confirmation=28
category=receive
account=Firstaccount
address=1L2T5DvEx8cHTkLJTwsexq6Faz4T3sDBnQ
amount=500000000
transactionid=00d31a97aa5e8b19a7b8a4340d540e5eb7c742bd88646425dbecc634c190455b
________________________________________
validateaddress command
isvalid - 1
address - 1L2T5DvEx8cHTkLJTwsexq6Faz4T3sDBnQ
ismine - 1
account - Firstaccount

I only went over a fraction of the API commands that are available. The goal was to get you use to using the API to get information from the Devcoin Wallet. For a complete list of the API commands, see the website https://en.bitcoin.it/wiki/Original_Bitcoin_client/API_Calls_list.

The goal of this tutorial is to show one how to communicate with the Devcoin Wallet using PHP and the JSON-RPC protocol. Firstly, I showed how to set up the Devcoin.conf file so that the Devcoin Wallet will accept the JSON-RPC protocol. Then I demonstrated how to download and use the JSON-RPC library with PHP. And then I went through a couple of example of using the Devcoin API commands. After reading this tutorial one will be able to communicate with the Devcoin Wallet using PHP.

Computing