README
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
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). 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 |
// Configure Buttercoin instance. Only apiKey and apiSecret are required.
// The environment parameter defaults to the 'production' environment.
// The version parameter defaults to the latest version as of this release, 'v1'
var client = require('buttercoinsdk-node')('<api_key>', '<api_secret>', '<environment>', '<version>');
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.
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 parameter, it will default to the current timestamp.
client.getKey(function (err, key) {
// do something amazing!
});
Get Data
Key Permissions
Returns array
of permissions associated with this key
client.getKey(new Date().getTime(), function (err, key) {
console.log("key err", err);
console.log("key", key);
});
Balances
Returns array
of balances for this account
client.getBalances(new Date().getTime(), function (err, balances) {
console.log("balances err", err);
console.log("balances", balances);
});
Deposit Address
Returns bitcoin address string
to deposit your funds into the Buttercoin platform
client.getDepositAddress(new Date().getTime(), function (err, address) {
console.log("address err", err);
console.log("address", address);
});
Get Orders
Returns array
of JSON 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, new Date().getTime(), function (err, orders) {
console.log("orders err", err);
console.log("orders", orders);
});
// single order by id
var orderId = '<order_id>';
client.getOrderById(orderId, new Date().getTime(), function (err, order) {
console.log("order err", err);
console.log("single order", order);
});
// single order by url
var url = '<url>';
client.getOrderByUrl(url, new Date().getTime(), function (err, order) {
console.log("order err", err);
console.log("single order", order);
});
Get Transactions
Returns array
of JSON Objects
containing information about deposit and withdraw action
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 trxnParams = {};
// the query parameter is optional and can be omitted for convenience to search all trxns
client.getTransactions(trxnParams, new Date().getTime(), function (err, orders) {
console.log("trxn err", err);
console.log("trxn", orders);
});
// single transaction by id
var trxnId = '53a22ce164f23e7301a4fee5';
client.getTransaction(trxnId, new Date().getTime(), function (err, transaction) {
console.log("single trxn err", err);
console.log("single trxn", transaction);
});
// single transaction by url
var url = 'https://api.buttercoin.com/v1/transactions/53e539aa64f23ec123931c11';
client.getTransaction(url, new Date().getTime(), function (err, transaction) {
console.log("single trxn err", err);
console.log("single trxn", transaction);
});
Unauthenticated Requests
Get Order Book
Return an array
of current orders in the Buttercoin order book
client.getOrderbook(function (err, orderBook) {
console.log("order book err", err);
console.log("order book", orderBook);
});
Get Ticker
Return the current bid, ask, and last sell prices on the Buttercoin platform
client.getTicker(function (err, ticker) {
console.log("ticker err", err);
console.log("ticker", ticker);
});
Get Trade History
Return the last 100 trades
client.getTradeHistory(function (err, trades) {
console.log("trades err", err);
console.log("trades", trades);
});
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 a JSON object with the following params
var 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);
});
Further Reading
Buttercoin - Website
Buttercoin API Documentation
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
1.0.0
- Added the ability to connect to a custom endpoint instead of just staging or production
Prereleases
- Added trade history endpoint
- Changed test env to sandbox.buttercoin.com
- Made timestamp an optional parameter (will default to current timestamp)
- Made getOrders and getTransactions query params optional
- Fixed issue with self not defined
- Fixed issue with orderbook returning null
- Added support for unauthenticated requests
- Fixed README format and accuracy
- First release.
License
Licensed under the MIT license.