buttercoin/buttercoin-sdk

A PHP library for connecting to the Buttercoin API

0.0.6 2014-10-08 17:22 UTC

Requires

• php: >=5.3.3
• guzzle/guzzle: ~3.8.1

Requires (Dev)

• phpunit/phpunit: *

MIT

• Kevin Adams

• bitcoin
• btc
• cryptocurrency
• trading
• buttercoin

README

Easy integration with the Buttercoin Trading Platform through our API.

Installation with Composer

$ php composer.phar require buttercoin/buttercoin-sdk:~0.0.6

Usage

For composer documentation, please refer to getcomposer.org.

This client was built using Guzzle, a PHP HTTP client & framework for building RESTful web service clients.

When you first create a new ButtercoinClient instance you can pass publicKey, privateKey, and environment as configuration settings. These are optional and can be later specified through Setter methods.

For authenticated API Resources, the publicKey and secretKey are required and can also be passed to the factory method in the configuration array. The environment configuration setting defaults to 'production'.

For a list of required and available parameters for the different API Endpoints, please consult the Buttercoin API Reference Docs.

Configuring the Client

The factory method accepts an array of configuration settings for the Buttercoin Webservice Client.

Setting	Property Name	Description
Public Key	publicKey	Your Buttercoin API Public Key
Secret Key	secretKey	Your Buttercoin API Secret Key
Environment	environment	Your development environment (default: 'production', set to 'sandbox' to test with testnet bitcoins)
API Version	version	The API Version. Currently used to version the API URL and Service Description

Example

require 'vendor/autoload.php';
use Buttercoin\Client\ButtercoinClient;
date_default_timezone_set('UTC'); // for $timestamp

$client = ButtercoinClient::factory([
	'publicKey' => '<public_key>',
	'secretKey' => '<secret_key>',
	'environment' => 'sandbox' // leave this blank for production
]);

Configuration can be updated to reuse the same Client:

You can reconfigure the Buttercoin Client configuration options through available getters and setters. You can get and set the following options: publicKey, secretKey, environment, & version

Example

$client->getSecretKey();
$client->setSecretKey('<new_secret_key>');

Tips

A note on the timestamp param sent to all client methods: This param must always be increasing, and within 5 minutes of Buttercoin server times (GMT). This is to prevent replay attacks on your data.

Before every call, get a new timestamp. (You need only set the timezone once)

date_default_timezone_set('UTC'); // Do this only once
$timestamp = round(microtime(true) * 1000);
$client->getKey($timestamp);

Additionally, for convenience, if you don't include the timestamp parameter, it will default to the current timestamp.

$client->getKey();

WARNING

For Query and Post Params, there is a limitation from the Guzzle library that you always add the params to your array in the order they are displayed in tables below. If you don't do this, the HMAC-SHA256 signature will not be correct and you will get a 401 request error.

Get Data

Unauthenticated

Get Order Book
Return an array of current orders in the Buttercoin order book

$client->getOrderBook();

Get Trade History
Return an array of the last 100 trades

$client->getTradeHistory();

Get Ticker
Return the current bid, ask, and last sell prices on the Buttercoin platform

$client->getTicker();

Authenticated

Key Permissions
Returns array of permissions associated with this key

$client->getKey($timestamp);

Balances
Returns array of balances for this account

$client->getBalances($timestamp);

Deposit Address
Returns bitcoin address string to deposit your funds into the Buttercoin platform

$client->getDepositAddress($timestamp);

Get Orders
Returns array of arrays containing information about buy and sell orders

Valid params include (must be added to array in this order):

Name	Param	Description
Status	status	enum: ['opened', 'partial-filled', 'filled', 'canceled']
Side	side	enum: ['buy', 'sell']
Order Type	orderType	enum: ['market', 'limit']
Date Min	dateMin	format: ISO-8601, e.g. '2014-05-06T13:15:30Z'
Date Max	dateMax	format: ISO-8601, e.g. '2014-05-06T13:15:30Z'

// query for multiple orders
$orderParams = [ "status" => "canceled", "side" => "sell" ];

$client->getOrders($orderParams, $timestamp);

// single order by id
$orderId = '<order_id>';

$client->getOrderById($orderId, $timestamp);

// single order by url
$url = 'https://api.buttercoin.com/v1/orders/{order_id}';

$client->getOrderByUrl($url, $timestamp);

Get Transaction
Returns array of arrays containing information about deposit and withdraw action

Valid params include (must be added to array in this order):

Name	Param	Description
Status	status	enum: ['pending', 'processing', 'funded', 'canceled', 'failed']
Transaction Type	transactionType	enum: ['deposit', 'withdrawal']
Date Min	dateMin	format: ISO-8601, e.g. '2014-05-06T13:15:30Z'
Date Max	dateMax	format: ISO-8601, e.g. '2014-05-06T13:15:30Z'

// query for multiple transactions
$trxnParams = [ "status" => "funded", "transactionType" => "deposit" ];

$client->getTransactions($trxnParams, $timestamp);

$trxnId = '53a22ce164f23e7301a4fee5';

$client->getTransactionById($trxnId, $timestamp);

// single transaction by url
$url = 'https://api.buttercoin.com/v1/transactions/{transaction_id}';

$client->getTransactionByUrl($url, $timestamp);

Create New Actions

Create Order

Valid order params include:

Name	Param	Description
Instrument	instrument	enum: ['BTC_USD, USD_BTC']
Side	side	enum: ['buy', 'sell'], required true
Order Type	orderType	enum: ['limit', 'market'], required true
Price	price	string, required false
Quantity	quantity	string, required false

// create an array with the following params
$order = [
  "instrument" => "BTC_USD",
  "side" => "buy",
  "orderType" => "limit",
  "price" => "700.00"
  "quantity" => "5"
];

$client->createOrder($order, $timestamp);

Create Transaction

Please contact Buttercoin support before creating a USD deposit using the API

Deposit transaction params include:

Name	Param	Description
Method	method	enum: ['wire'], required true
Currency	currency	enum: ['USD'], required true
Amount	amount	string, required true

// create deposit
$trxnObj = [
  "method" => "wire",
  "currency" => "USD",
  "amount" => "5002"
];

$client->createDeposit($trxnObj, $timestamp);

Withdrawal transaction params include:

Name	Param	Description
Method	method	enum: ['check'], required true
Currency	currency	enum: ['USD'], required true
Amount	amount	string, required true

// create withdrawal
$trxnObj = [
  "method" => "check",
  "currency" => "USD",
  "amount" => "900.23"
];

$client->createWithdrawal($trxnObj, $timestamp);

Send bitcoin transaction params include:

Name	Param	Description
Currency	currency	['USD'], required true
Amount	amount	string, required true
Destination	destination	address to which to send currency string, required true

// send bitcoins to an address
$trxnObj = [
  "currency" => "BTC",
  "amount" => "100.231231",
  "destination" => "<bitcoin_address>"
];

$client->sendCrypto($trxnObj, $timestamp);

Cancel Actions

All successful cancel calls to the API return a response status of 204 with a human readable success message

Cancel Order
Cancel a pending buy or sell order

$client->cancelOrder($orderId, $timestamp);

Cancel Transaction
Cancel a pending deposit or withdraw action

$client->cancelTransaction($trxnId, $timestamp);

Further Reading

Buttercoin - Website
Buttercoin API Docs

Contributing

This is an open source project and we love involvement from the community! Hit us up with pull requests and issues.

The aim is to take your great ideas and make everyone's experience using Buttercoin even more powerful. The more contributions the better!

Release History

0.0.6

• added trade history endpoint

0.0.5

• changed test env to sandbox

0.0.3

• changed withdraw endpoint from /withdrawal to /withdraw

0.0.2

• Made timestamp an optional field, defaults to current timestamp
• Fixed errors in README file

0.0.1

• First release.

License

Licensed under the MIT license.