valr-api-node v2.1.0

valr-api-node

valr-api-node is a simple node.js wrapper for VALR REST and WebSocket API.

Clients for both the REST API and streaming WebSocket API are included.

Contents

• Changelog
• Installation
• Quick examples
• API
• Contributors
• License

Changelog

See detailed Changelog

Installation

npm install --save valr-api-node

Quick examples

REST API example:

import Valr from 'valr-api-node'

const valr = new VALR({ key, secret })
valr.getMarketSummary({ currencyPair: 'BTCZAR' })
  .then(console.log)
  .catch(console.error)

WebSocket API examples:

import Valr from 'valr-api-node'

const valr = new Valr({ key, secret })
let accountWebSocket = valr.newAccountWebSocket()

accountWebSocket.onopen = () => {
  console.log('Websocket is open')
}
  
accountWebSocket.onmessage = (message) => {
  let data = JSON.parse(message.data)
  console.log('Websocket data received')
}

import Valr from 'valr-api-node'

const valr = new Valr({ key, secret })
let tradeWebSocket = valr.newTradeWebSocket()

tradeWebSocket.onopen = () => {
  console.log('Websocket is open')
}
  
tradeWebSocket.onmessage = (msg) => {
  if (msg.type === 'message' && JSON.parse(msg.data).type === 'AUTHENTICATED') {
    const subscribeMessage = {
      type: 'SUBSCRIBE',
      subscriptions: [
        {
          event: 'MARKET_SUMMARY_UPDATE',
          pairs: ['BTCZAR']
        }
      ]
    }
    tradeWebSocket.send(JSON.stringify(subscribeMessage))
  }

  if (msg.type === 'message' && JSON.parse(msg.data).type === 'MARKET_SUMMARY_UPDATE') {
    console.log(msg.data)
  }
}

tradeWebSocket.onerror = (...args) => {
}

Constructor

Valr({ key, secret, key2, secret2 })

key and secret are required for authenticated API requests.

A secondary pair of API key and secret can be provided, in which case the authenticated API calls will be made alternatively, one with the primary key/secret one with the secondary key/secret. This feature can be used to take advantage of double API rate limit.

REST API

All methods return promises.

Properties

apiCallRate

Gives the current rate of API calls. The property is read only. The counter is reset at the start of each minute.

It can be used by applications to limit the API call rate to prevent HTTP error code 429 (too many requests) responses from VALR server.

See VALR API documentation for applicable rate limitations: Rate limiting

Public APIs

getCurrencies()

Get a list of currencies supported by VALR :bookmark_tabs:.

getCurrencyPairs()

Get all the order types supported for all currency pairs :bookmark_tabs:.

getOrderTypes({ currencyPair })

Get all the order types supported for all currency pairs :bookmark_tabs: or for a given currency pair :bookmark_tabs:.

getMarketSummary({ currencyPair })

Get the market summary for all currency pairs :bookmark_tabs: or for a given currency pair :bookmark_tabs:.

getServerTime()

Get the server time :bookmark_tabs:.

getStatus()

Get the current status of VALR :bookmark_tabs:.

Account

The following APIs allow you to query your account balances and full transaction history. These APIs are protected and will require authentication.

getApiKeyInfo()

Returns the current API Key's information and permissions :bookmark_tabs:.

getBalances()

Returns the list of all wallets with their respective balances:bookmark_tabs:.

getAccountTransactionHistory({ skip, limit })

Get the transaction history for your account:bookmark_tabs:.

getAccountTradeHistory({limit, currencyPair })

Get the last 100 recent trades for the given currency pair for your account:bookmark_tabs:.

Wallets

Access your wallets programmatically.

getDepositAddress({ currencyCode })

Returns the default deposit address associated with currency specified with the parameter currencyCode :bookmark_tabs:.

getWithdrawalInfo({ currencyCode })

Get all the information about withdrawing a given currency from your VALR account:bookmark_tabs:.

newWithdrawal({ currencyCode, amount, address, paymentReference })

Withdraw cryptocurrency funds to an address:bookmark_tabs:.

getWithdrawalStatus({ currencyCode, withdrawId })

Check the status of a withdrawal :bookmark_tabs:.

getDepositHistory({ currencyCode, skip, limit })

Get the Deposit History records for a given currency :bookmark_tabs:.

getWithdrawalHistory({ currencyCode, skip, limit })

Get Withdrawal History records for a given currency :bookmark_tabs:.

getBankAccounts({ currencyCode })

Get a list of bank accounts that are bookmark_tabsed to your VALR account :bookmark_tabs:.

newFiatWithdrawal({ currencyCode, amount, linkedBankAccountId })

Withdraw cryptocurrency funds to an address:bookmark_tabs:.

Market Data

These API calls can be used to receive the market data.

getOrderBook({ currencyPair, full })

Withdraw cryptocurrency funds to an address:bookmark_tabs:.

getTradeHistory({ currencyPair, limit })

Withdraw cryptocurrency funds to an address:bookmark_tabs:.

Simple Buy/Sell

Make use of our powerful Simple Buy/Sell API to instantly buy and sell currencies.

getSimpleQuote({ currencyPair, payInCurrency, payAmount, side })

Get a quote to buy or sell instantly using Simple Buy:bookmark_tabs:.

simpleOrder({ currencyPair, payInCurrency, payAmount, side })

Submit an order to buy or sell instantly using Simple Buy/Sell:bookmark_tabs:.

getSimpleOrderStatus({ currencyPair, orderId })

Submit an order to buy or sell instantly using Simple Buy/Sell:bookmark_tabs:.

##Exchange Buy/Sell Make use of our powerful Exchange Buy/Sell APIs to place your orders on the Exchange programmatically.

limitOrder({ side, quantity, price, pair, postOnly, customerOrderId })

Create a new limit order :bookmark_tabs:.

marketOrder({ side, amount, pair, customerOrderId })

Create a new market order :bookmark_tabs:.

stopLimitOrder({ side, amount, pair, customerOrderId })

Create a new market order :bookmark_tabs:.

batchOrders({ requests })

Create a batch of multiple orders, or cancel orders, in a single request :bookmark_tabs:. See VALR API documentation for applicable parameters.

getOrderStatus({ orderId, customerOrderId })

Returns the status of an order that was placed on the Exchange queried using the orderId :bookmark_tabs: or customerOrderId :bookmark_tabs:.

getOpenOrders()

Returns all open orders for your account :bookmark_tabs:.

getOrderHistory({ skip, limit })

Returns historical orders placed by you :bookmark_tabs:.

getOrderHistorySummary({ orderId, customerOrderId })

Returns a more detailed summary about an order queried using the orderId :bookmark_tabs: or customerOrderId :bookmark_tabs:.

Detailed summary can be requested for an order when the getOrderStatus API call returns one of the following statuses: Filled, Cancelled or Failed.

getOrderHistoryDetail({ orderId, customerOrderId })

Returns detailed history of an order's statuses queried using the orderId :bookmark_tabs: or customerOrderId :bookmark_tabs:.

This call returns an array of "Order Status" objects. The latest and most up-to-date status of this order is the zeroth element in the array.

cancelOrder({ pair, orderId, customerOrderId })

Cancel an open order :bookmark_tabs:.

WebSocket API

Connection

The methods return a WebSocket object. The WebSocket class that is used to create the websocket can be specified as parameter.

newAccountWebSocket([WebSocketClass, options])

Establishes a WebSocket connection to receive streaming updates about your VALR account.

newTradeWebSocket([WebSocketClass, options])

Establishes a WebSocket connection to receive streaming updates about Trade data.

Events subscribing and unsubscribing

Once you open a connection to 'Account', you are automatically subscribed to all messages for all events on the 'Account' WebSocket connection. You will start receiving message feeds pertaining to your VALR account. For example, you will receive messages when your balance is updated or when a new trade is executed on your account.

On the other hand, When you open a connection to 'Trade', in order to receive message feeds about trading data, you must subscribe to events you are interested in on the 'Trade' WebSocket connection.

When you are no longer interested in receiving messages for certain events on the 'Trade' WebSocket connection, you can send a unsubscribe message.

See VALR Websocket API documentation on how to subscribe and unsubscribe to 'Trade' events.

Message Feeds

See VALR Websocket API documentation

License

MIT