GDAX

The official Node.js library for Coinbase's GDAX API.

Note: this library may be subtly broken or buggy. The code is released under the MIT License – please take the following message to heart:

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Features

• Easy functionality to use in programmatic trading
• A customizable, websocket-synced Order Book implementation
• API clients with convenient methods for every API endpoint
• Abstracted interfaces – don't worry about HMAC signing or JSON formatting; the library does it for you
• Semantic versioning

Installation

# from npm
npm install gdax

# from GitHub
npm install coinbase/gdax-node

You can learn about the API responses of each endpoint by reading our documentation.

Quick Start

The GDAX API has both public and private endpoints. If you're only interested in the public endpoints, you should use a PublicClient.

const Gdax = require('gdax');
const publicClient = new Gdax.PublicClient();

All methods, unless otherwise specified, can be used with either a promise or callback API.

Using Promises

publicClient
  .getProducts()
  .then(data => {
    // work with data
  })
  .catch(error => {
    // handle the error
  });

The promise API can be used as expected in async functions in ES2017+ environments:

async function yourFunction() {

  try {

    const products = await publicClient.getProducts();

  } catch(error) {
    /* ... */
  }

}

Using Callbacks

Your callback should accept two arguments:

• error: contains an error message (string), or null if no was error encountered
• response: a generic HTTP response abstraction created by the request library
• data: contains data returned by the GDAX API, or undefined if an error was encountered

publicClient.getProducts((error, response, data) => {
  if (error) {
    // handle the error
  } else {
    // work with data
  }
});

NOTE: if you supply a callback, no promise will be returned. This is to prevent potential UnhandledPromiseRejectionWarnings, which will cause future versions of Node to terminate.

const myCallback = (err, response, data) => { /* ... */ };

const result = publicClient.getProducts(myCallback);

result.then(() => { /* ... */ }); // TypeError: Cannot read property 'then' of undefined

Optional Parameters

Some methods accept optional parameters, e.g.

publicClient
  .getProductOrderBook({ level: 3 })
  .then(book => { /* ... */ });

To use optional parameters with callbacks, supply the options as the first parameter(s) and the callback as the last parameter:

publicClient
  .getProductOrderBook({ level: 3 }, (error, response, book) => { /* ... */ });

The Public API Client

const publicClient = new Gdax.PublicClient(productID, endpoint);

• productID optional - defaults to 'BTC-USD' if not specified.
• endpoint optional - defaults to 'https://api.gdax.com' if not specified.

Public API Methods

• getProducts

publicClient.getProducts(callback);

• getProductOrderBook

// Get the order book at the default level of detail.
publicClient.getProductOrderBook(callback);

// Get the order book at a specific level of detail.
publicClient.getProductOrderBook({'level': 3}, callback);

• getProductTicker

publicClient.getProductTicker(callback);

• getProductTrades

publicClient.getProductTrades(callback);

// To make paginated requests, include page parameters
publicClient.getProductTrades({'after': 1000}, callback);

• getProductTradeStream

Wraps around getProductTrades, fetches all trades with IDs >= tradesFrom and <= tradesTo. Handles pagination and rate limits.

const trades = publicClient.getProductTradeStream(8408000, 8409000);

// tradesTo can also be a function
const trades = publicClient.getProductTradeStream(8408000, trade => Date.parse(trade.time) >= 1463068e6);

• getProductHistoricRates

publicClient.getProductHistoricRates(callback);

// To include extra parameters:
publicClient.getProductHistoricRates({'granularity': 3000}, callback);

• getProduct24HrStats

publicClient.getProduct24HrStats(callback);

• getCurrencies

publicClient.getCurrencies(callback);

• getTime

publicClient.getTime(callback);

The Authenticated API Client

The private exchange API endpoints require you to authenticate with a GDAX API key. You can create a new API key in your exchange account's settings. You can also specify the API URI (defaults to https://api.gdax.com).

const key = 'your_api_key';
const b64secret = 'your_b64_secret';
const passphrase = 'your_passphrase';

const apiURI = 'https://api.gdax.com';
const sandboxURI = 'https://api-public.sandbox.gdax.com';

const authedClient = new Gdax.AuthenticatedClient(key, b64secret, passphrase, apiURI);

Like PublicClient, all API methods can be used with either callbacks or will return promises.

AuthenticatedClient inherits all of the API methods from PublicClient, so if you're hitting both public and private API endpoints you only need to create a single client.

Private API Methods

• getCoinbaseAccounts

authedClient.getCoinbaseAccounts(callback);

• getAccounts

authedClient.getAccounts(callback);

• getAccount

const accountID = '7d0f7d8e-dd34-4d9c-a846-06f431c381ba';
authedClient.getAccount(accountID, callback);

• getAccountHistory

const accountID = '7d0f7d8e-dd34-4d9c-a846-06f431c381ba';
authedClient.getAccountHistory(accountID, callback);

// For pagination, you can include extra page arguments
authedClient.getAccountHistory(accountID, {'before': 3000}, callback);

• getAccountHolds

const accountID = '7d0f7d8e-dd34-4d9c-a846-06f431c381ba';
authedClient.getAccountHolds(accountID, callback);

// For pagination, you can include extra page arguments
authedClient.getAccountHolds(accountID, {'before': 3000}, callback);

• buy, sell

// Buy 1 BTC @ 100 USD
const buyParams = {
  'price': '100.00', // USD
  'size': '1',  // BTC
  'product_id': 'BTC-USD',
};
authedClient.buy(buyParams, callback);

// Sell 1 BTC @ 110 USD
const sellParams = {
  'price': '110.00', // USD
  'size': '1', // BTC
  'product_id': 'BTC-USD',
};
authedClient.sell(sellParams, callback);

• cancelOrder

const orderID = 'd50ec984-77a8-460a-b958-66f114b0de9b';
authedClient.cancelOrder(orderID, callback);

• cancelOrders

authedClient.cancelOrders(callback);

• cancelAllOrders

// `cancelOrders` may require you to make the request multiple times until
// all of the orders are deleted.

// `cancelAllOrders` will handle making these requests for you asynchronously.
// Also, you can add a `product_id` param to only delete orders of that product.

// The data will be an array of the order IDs of all orders which were cancelled
authedClient.cancelAllOrders({product_id: 'BTC-USD'}, callback);

• getOrders

authedClient.getOrders(callback);
// For pagination, you can include extra page arguments
authedClient.getOrders({'after': 3000}, callback);

• getOrder

const orderID = 'd50ec984-77a8-460a-b958-66f114b0de9b';
authedClient.getOrder(orderID, callback);

• getFills

authedClient.getFills(callback);
// For pagination, you can include extra page arguments
authedClient.getFills({'before': 3000}, callback);

• getFundings

authedClient.getFundings({}, callback);

• repay

const params = {
  'amount': '2000.00',
  'currency': 'USD'
};
authedClient.repay(params, callback);

• marginTransfer

const params =
  'margin_profile_id': '45fa9e3b-00ba-4631-b907-8a98cbdf21be',
  'type': 'deposit',
  'currency': 'USD',
  'amount': 2
};
authedClient.marginTransfer(params, callback);

• closePosition

const params = {
  'repay_only': false
};
authedClient.closePosition(params, callback);

• deposit, withdraw

// Deposit to your Exchange USD account from your Coinbase USD account.
const depositParamsUSD = {
  'amount': '100.00',
  'currency': 'USD',
  'coinbase_account_id': '60680c98bfe96c2601f27e9c', // USD Coinbase Account ID
};
authedClient.deposit(depositParamsUSD, callback);

// Withdraw from your Exchange USD account to your Coinbase USD account.
const withdrawParamsUSD = {
  'amount': '100.00',
  'currency': 'USD',
  'coinbase_account_id': '60680c98bfe96c2601f27e9c', // USD Coinbase Account ID
};
authedClient.withdraw(withdrawParamsUSD, callback);

// Deposit to your Exchange BTC account from your Coinbase BTC account.
const depositParamsBTC = {
  'amount': '2.0',
  'currency': 'BTC',
  'coinbase_account_id': '536a541fa9393bb3c7000023', // BTC Coinbase Account ID
};
authedClient.deposit(depositParamsBTC, callback);

// Withdraw from your Exchange BTC account to your Coinbase BTC account.
const withdrawParamsBTC = {
  'amount': '2.0',
  'currency': 'BTC',
  'coinbase_account_id': '536a541fa9393bb3c7000023', // BTC Coinbase Account ID
};
authedClient.withdraw(withdrawParamsBTC, callback);

// Withdraw from your Exchange BTC account to another BTC address.
const withdrawAddressParams = {
  'amount': 10.00,
  'currency': 'BTC',
  'crypto_address': '15USXR6S4DhSWVHUxXRCuTkD1SA6qAdy'
}
authedClient.withdrawCrypto(withdrawAddressParams, callback);

• getTrailingVolume

// Get your 30 day trailing volumes
authedClient.getTrailingVolume(callback);

Websocket Client

The WebsocketClient allows you to connect and listen to the exchange websocket messages.

const websocket = new Gdax.WebsocketClient(['BTC-USD', 'ETH-USD']);

websocket.on('message', data => { /* work with data */ });
websocket.on('error', err => { /* handle error */ });
websocket.on('close', () => { /* ... */ });

Optionally set the heartbeat mode or websocket URI.

const websocket = new Gdax.WebsocketClient(
  ['BTC-USD','ETH-USD'],
  'https://api-public.sandbox.gdax.com',
  {
    key: 'suchkey',
    secret: 'suchsecret',
    passphrase: 'muchpassphrase',
  },
  { heartbeat: true }
);

The following events can be emitted from the WebsocketClient:

• open
• message
• close
• error

Orderbook

Orderbook is a data structure that can be used to store a local copy of the orderbook.

const orderbook = new Gdax.Orderbook();

The orderbook has the following methods:

• state(book)
• get(orderId)
• add(order)
• remove(orderId)
• match(match)
• change(change)

Orderbook Sync

OrderbookSync creates a local mirror of the orderbook on GDAX using Orderbook and WebsocketClient as described here.

const orderbookSync = new Gdax.OrderbookSync(['BTC-USD', 'ETH-USD']);
console.log(orderbookSync.books['ETH-USD'].state());

Testing

npm test

# test for known vulnerabilities in packages
npm install -g nsp
nsp check --output summary