Buttercoin API Node.js Client

Official Node.js Client of the Buttercoin API. Buttercoin is a trading platform that makes buying and selling bitcoin easy.

Getting Started

Use npm to install

npm install buttercoin-node

Examples

Initialization

For authenticated requests, the API client must use either a key/secret pair or an OAuth2 bearer token.

Common

Setting	Property Name	Description
Environment	`environment`	Your development environment (default: `'production'`, set to `'sandbox'` to test with testnet bitcoins). You can set this to an object with `host`, `protocol` (defaults to `'https'`), `port` (defaults to empty), and `headers` (defaults to `[]`) for custom endpoints.
API Version	`version`	The API Version. Currently used to version the API URL and Service Description

Key/Secret

Setting	Property Name	Description
Key	`key`	Your Buttercoin API Key
Secret	`secret`	Your Buttercoin API Secret

// Configure Buttercoin client instance.  Only apiKey and apiSecret are required.
// The environment parameter defaults to the sandbox environment.
// The version parameter defaults to the latest version as of this release, 'v1'

var Buttercoin = require('buttercoin-node');
var API_KEY = // the Key ...
var API_SECRET = // the Secret ...
var env = Buttercoin.Environment.production;
var client = Buttercoin.withKeySecret(API_KEY, API_SECRET, environment, 'v1');

OAuth2

Setting	Property Name	Description
Token Provider	`tokenProvider`	A function which take some credential evidence (e.g. a user session id) and maps it to a bearer token string

// Only tokenProvider is required, environment and version default as above

var Buttercoin = require('buttercoin-node');
function tokenProvider(evidence) { /* lookup bearer tokens... */ }
var client = Buttercoin.withOAuth2(tokenProvider);

Conventions

Promises

All API calls produce a Q promise. We may support callback or event style interfaces if there's interest.

Timestamps

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

Because of this, if you need your API calls to run in a certain order, you must chain together callbacks to ensure synchronous responses to your requests.

var timestamp = new Date().getTime();

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

// API key/secret is configured on the client instance

// With explicit timestamp
client.getBalances({timestamp: new Date().getTime()});

// With automatic timestamp
client.getBalances()
  .then(/* do something ... */)
  .done();

Evidence

When using an OAuth2 client, you need to provide 'evidence' that can be used to derive a bearer token for a specific user.

Unlike in the case of timestamps, this must be passed to any method requiring authentication.

var sessionId = // a user session ID which can be used to lookup a bearer token
client.getBalances(sessionId)
  .then(/* do something ... */)
  .done();

Getting Data

Credential Permissions Returns a promise for an array of permissions associated with this API key or bearer token.

client.getPermissions();

Balances Returns a promise for an object. Each key indicates a currency code (currently 'USD' or 'BTC'. Each associated value is a number representing the amount of that currency available.

client.getBalances();

Deposit Address Returns a promise for a bitcoin address string which can be used to deposit bitcoins into this account.

client.getDepositAddress();

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

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
var orderParams = { side: 'sell' };
// the query parameter is optional and can be omitted for convenience to search all orders
client.getOrders(orderParams);

// single order by id
var orderId = '<order_id>';
client.getOrderById(orderId);

// single order by url
var url = '<url>';
client.getOrderByUrl(url);

Get Transactions Returns array of objects containing information about deposits and withdrawals.

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
var txParams = {};
// the query parameter is optional and can be omitted for convenience to search all trxns
client.getTransactions(txParams);

// single transaction by id
var txId = '53a22ce164f23e7301a4fee5';
client.getTransaction(txId);

// single transaction by url
var url = 'https://api.buttercoin.com/v1/transactions/53e539aa64f23ec123931c11';
client.getTransaction(url);

Unauthenticated Requests

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

client.getOrderbook();

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

client.getTicker();

Get Trade History Return the last 100 trades

client.getTradeHistory();

Create New Actions

*** Calls below this line are out of date *** 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 a JSON object with the following params
var order = new client.Order({
  instrument: "BTC_USD",
  orderAction: "buy",
  orderType: "limit",
  price: "700.00"
  quantity: "5"
});

client.createOrder(order, new Date().getTime(), function (err, order) {
  console.log("create order err", err);
  console.log("create order", order);
});

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
var trxnObj = {
  method: "wire",
  currency: "USD",
  amount: "5002"
};

client.createDeposit(trxnObj, new Date().getTime(), function (err, trxn) {
  console.log("create trxn err", err);
  console.log("create trxn", trxn);
});

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
var trxnObj = {
  method: "check",
  currency: "USD",
  amount: "100"
};

client.createWithdrawal(trxnObj, new Date().getTime(), function (err, trxn) {
  console.log("create trxn err", err);
  console.log("create trxn", trxn);
});

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
var trxnObj = {
  currency: "BTC",
  amount: "100.231231",
  destination: "<bitcoin_address>"
};

client.sendBitcoin(trxnObj, new Date().getTime(), function (err, trxn) {
  console.log("create trxn err", err);
  console.log("create trxn", trxn);
});

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, new Date().getTime(), function (err, msg) {
  console.log("cancel order err", err);
  console.log("cancel order", msg);
});

Cancel Transaction Cancel a pending deposit or withdraw action

client.cancelTransaction(trxnId, new Date().getTime(), function (err, msg) {
  console.log("cancel trxn err", err);
  console.log("cancel trxn", msg);
});