EMX

The official Node.js library for the EMX API.

Features

• Public, Authenticated, and WebSocket API client libraries
• Built-in HMAC signing

Installation

npm install emx

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

Quick Start

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

const EMX = require('emx');
const publicClient = new EMX.PublicClient();

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

Using Promises

publicClient
  .getContracts()
  .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 contracts = await publicClient.getContracts();
  } catch (error) {
    /* ... */
  }
}

Using Callbacks

Your callback should accept three arguments:

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

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

The Public API Client

const publicClient = new EMX.PublicClient(apiURI);

• apiURI optional - defaults to 'https://api.testnet.emx.com' if not specified.

Public API Methods

These methods allow you to pull public contract information and market data. You may pass pagination and filtering parameters, as described in the EMX API documentation. These methods are subject to rate limiting.

• getContract(contractcode), getContracts(), getActiveContracts()

// get metadata for all active contracts.
publicClient.getActiveContracts(callback);

• getContractL2OrderBook()
• getContractQuote()
• getContractAuction(auctionCode), getContractAuctions(contractCode)

The Authenticated API Client

The private exchange API endpoints require you to authenticate with an EMX 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.testnet.emx.com).

const authedClient = new EMX.AuthenticatedClient(
  'your_api_key', 'your_b64_secret', 'https://api.testnet.emx.com',
);

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

• placeOrder()

// Buy 5.01 BTCH19 @ 3800 USD
const buyParams = {
  contractCode: 'BTCH19',
  side: 'buy',
  size: '5.0125', // BTC
  price: '3800.00', // USD
  type: 'limit',
};
authedClient.placeOrder(buyParams, callback);

// Sell 2.5 BTCH19 @ 3800 USD
const sellParams = {
  contractCode: 'BTCH19',
  side: 'sell',
  size: '2.5', // BTC
  price: '3800.00', // USD
  type: 'limit',
};
authedClient.placeOrder(sellParams, callback);

• getOrder(orderId), getOrders()
• modifyOrder(orderId, mods)
• cancelOrder(orderId), cancelOrders(contractCode)
• getFills()
• getPositions()
• getAccount(traderId), getAccounts()

WebSocket Client

The WebSocketClient allows you to connect and listen to (and send) the exchange WebSocket messages.

const websocket = new EMX.WebSocketClient(['BTCH19']);

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

To access higher rate limits and/or to enable trading across the socket, you may authenticate with an EMX API key. You can create a new API key in your exchange account's settings. You can also specify the API URI (defaults to wss://api.testnet.emx.com).

const websocket = new EMX.WebSocketClient(
  'your_api_key', 'your_b64_secret', 'wss://api.testnet.emx.com',
);

Once you create the WebSocketClient object, you'll be connected to the socket and you may subscribe to channels:

websocket.subscribe({ contractCodes: ['BTCH19'], channels: ['auctions', 'level2'] });

websocket.unsubscribe({ channels: ['auctions'] });

The following events will be emitted from the WebSocketClient:

• open
• message
• close
• error

If you subscribe to the trading channel, you may call the following order-management methods:

• placeOrder(params)
• modifyOrder(params)
• cancelOrder(orderId), cancelOrders(contractCode)