radex-js v1.0.24

��# radex-js A javascript/typescript client library for Radex exchange.

Important note

This is still a development version of radex-js and is likely to contain bugs.

Installation

Use the Node.js (http://nodejs.org) package manager npm (to install radex-js

npm install radex-js

Update

radex-js is still under active development. It is suggested you check for updates regularly. To update your radex-js, you can run npm update.

npm update

Usage

Importing the radex-js librabry into your project

The easiest method is to just import all the radex types, functions and state available from the radex-js librabry as one variable into your project.

import * as radex from 'radex-js';

We will assume this method for the rest of the code examples.

Establishing a connection to RaDEX

To establish a connection to RaDEX, you need to run the imported connect function with the path to the radex websocket api (current test path = "wss://radex-api.herokuapp.com").

This function will connect to RaDEX and update the RaDEX state variables.

radex.connect("wss://radex-api.herokuapp.com");

Establishing a connection to RaDEX and setting initial state values

The connect function runs asyncronously and therefore does not connect to Radex immediately once called. The connect function provides a callback function as an optional 2nd paramter. This callback function will be called as soon as a connection with Radex has been established and can be used to set any initial Radex state variables (e.g. currentPair state variable).

e.g. To set the initial currentPair to "BTC-XRD" and the initial pairSliceDur to "15m" you could do it like this:

radex.connect("wss://radex-api.herokuapp.com", onOpen);

function onOpen() {
  radex.state.setCurrentPair("BTC-XRD");  // example usage
  radex.state.pairSliceDur("15m");  //example usage
}

If you try to set Radex state variables before the connection to Radex is established, it will not work.

Accessing RaDEX state variables

You can access all the radex-js state variables through the imported state variable.

E.g. to access the connected state variable you will have something like this:

constant connectedToRadex = radex.state.connected; // example usage

##RaDEX functions radex-js provides functions to submit and cancel orders.

submitOrder function

The submitOrder function is used to submit a new order to RaDEX.

Usage:

radex.submitOrder(orderObj)

Paramaters:

orderObj = {
    owner: string * // id of wallet that is submitting the order
    pair: string * // code of pair that this order is for
    token1: string * // code of token1 of pair
    token2: string * // code of token2 of pair
    side: OrderSide * // side of this order (see OrderSide enum)
    type: OrderType *// type of order (see OrderType enum)
    quantity: number  *1 // quantity of token1 specified for order
    price: number *2 // price for order, specified in token2 terms
    value: number *3 // value of order specfied as token2 quantity
    quantitySpecified: boolean (true if not specifeid) // whether exact order quantity or value must be fulfilled
}

* required fields
*1 quantity is required if order type is not "MARKET" and quanitySpecified is true
*2 price is required if order type is not "MARKET"
*3 value is required if order type is not "MARKET"  and quantitySpecified is false.

Return value

The submitOrder function returns a promise with a result object

Promise<{
    success: boolean  // true if order was submitted successfully
    result: string  // if success = true => id of order that has been submitted
                    // if success = false => error message
}>

cancelOrder function

The cancelOrder function is used to cancel an unfulfilled order.

Usage:

radex.cancelOrder(order_id)

Paramaters:

order_id: string  // the id of the order that must be cancelled

Return value

The cancelOrder function returns a promise with a result object

Promise<{
    success: boolean  // true if order was cancelled successfully
    result: string  // if success = true => id of order that has been cancelled
                    // if success = false => error message
}>

RaDEX State Variables

The RaDEX state variables provide easy access to up-to-date information on RaDEX. Most of the variables also have an Observable version indicated by a "$" at the end of the variable name.

connected / connected$

connected: boolean
connected: Observable<boolean>

The connected variable indicates whether there is currently a working connection with RaDEX. The variable will be true if the connection is working or false otherwise.

The connected$ variable is an Observable version of the connected variable.

allPairs / allPairs$

allPairs: Map<string, Pair>
allPairs$: Observable<Map<string, Pair>

The allPairs variable provides a Map (also sometimes referred to as a hash table) of all the pairs available on RaDEX. The map is indexed by the code of the pair (see Pair type). E.g. to access the information for the "BTC-XRD" pair

const BTCXRDPairInfo = radex.state.allPairs.get("BTC-XRD");
console.log(BTCXRDPairInfo);
// {
//  code: "BTC-XRD",
//  token1: "BTC",
//  token2: "XRD",
//  token1Decimals: 8,
//  token2Decimals: 8,
//  liquidityFee: 0.001,
//  platformFee: 0.0005,
// }

The allPairs$ variable is an Observable version of the allPairs variable.

currentPair / currentPair$

currentPair: string;
currentPair$: Observable<string>

The currentPair variable indicates the code (symbol) for the currently selected pair. A full set of up-to-date information (e.g. orders, trades, orderbook etc) is provided for the currentPair in the state variable (see the pair related state variables that follow).

When the currentPair variable is updated, all the related state variables are also updated to reflect the new currentPair. The currentPair variable can be changed by simple assignment

radex.state.currentPair = "BTC-XRD";

or by calling the setCurrentPair function on the state variable

radex.state.setCurrentPair("BTC-XRD");

The currentPair$ variable is an Observable version of the currentPair variable.

pairInfo / pairInfo$

pairInfo: Pair;
pairInfo$: Observable<Pair>;

The pairInfo variable provides the basic pair info (see Pair type) for the currentPair.

The pairInfo$ variable is an Observable version of the pairInfo variable.

pairBuyOrders / pairBuyOrders$

pairBuyOrders: Map<string, Order>;
pairBuyOrders$: Observable<Map<string, Order>>;

The pairBuyOrders variable provides a Map of the buy orders for the currentPair. The Map is indexed by the order id (see Order type).

The pairBuyOrders$ variable is an Observable version of the pairBuyOrders variable.

pairSellOrders / pairSellOrders$

pairSellOrders: Map<string, Order>;
pairSellOrders$: Observable<Map<string, Order>>;

The pairSellOrders variable provides a Map of the sell orders for the currentPair. The Map is indexed by the order id (see Order type).

The pairSellOrders$ variable is an Observable version of the pairSellOrders variable.

pairCompletedOrders / pairCompletedOrders$

pairCompletedOrders: Map<string, Order>;
pairCompletedOrders$: Observable<Map<string, Order>>;

The pairCompletedOrders variable provides a Map of the completed orders for the currentPair. The Map is indexed by the order id (see Order type).

The pairCompletedOrders$ variable is an Observable version of the pairCompletedOrders variable.

pairOrderbookBuys / pairOrderbookBuys$

pairOrderbookBuys: Map<number, OrderbookEntry>;
pairOrderbookBuys$: Observable<Map<number, OrderbookEntry>>;

The pairOrderbookBuys variable provides a Map of the orderbook buy entries for the currentPair. The Map is indexed by the orderbook price (see OrderbookEntry type).

The pairOrderbookBuys$ variable is an Observable version of the pairOrderbookBuys variable.

pairOrderbookSells / pairOrderbookSells$

pairOrderbookSells: Map<number, OrderbookEntry>;
pairOrderbookSells$: Observable<Map<number, OrderbookEntry>>;

The pairOrderbookSells variable provides a Map of the orderbook sell entries for the currentPair. The Map is indexed by the orderbook price (see OrderbookEntry type).

The pairOrderbookSells$ variable is an Observable version of the pairOrderbookSells variable.

pairTrades / pairTrades$

pairTrades: Map<string, Trade>;
pairTrades$: Observable<Map<string, Trade>>;

The pairTrades variable provides a Map of the completed trades for the currentPair. The Map is indexed by the trade id (see Trade type).

The pairTrades$ variable is an Observable version of the pairTrades variable.

pairSliceDur

pairSliceDur: string;

The pairSliceDur variable indicates the duration of pairSlices that will be calculated for the currentPair variable.

The pairSliceDur variable can be set through normal assignment

radex.state.pairSliceDur = "15m";

The pairSliceDur variable can be set to any of the following values: "1m" | "5m" | "15m" | "30m" | "1h" | "4h" | "12h" | "1D" | "1W" | "1M" .

Every time the pairSliceDur variable is changed, the pairSlices varaible will be updated to reflect the newly selected slice duration.

pairSlices / pairSlices$

pairSlices: Map<number, TimeSlice>;
pairSlices$: Observable<Map<number, TimeSlice>>;

The pairSlices variable provides a Map of the selected duration (as selected in pairSliceDur variable) time slices for the currentPair. The Map is indexed by the start time of the time slice (see TimeSlice type).

The pairSlices$ variable is an Observable version of the pairSlices variable.

pairSlice24h / pairSlice24h$

pairSlice24h: TimeSlice;
pairSlice24h$: Observable<TimeSlice>;

The pairSlice24h variable provides a 24h time slice for the currentPair. This timeslice is updated every 5 minutes to reflect the last 24 hr timeslice info (see TimeSlice type).

The pairSlice24h$ variable is an Observable version of the pairSlice24h variable.

tickersLive / tickersLive$

tickersLive: boolean;
tickersLive$: Observable<boolean>;

The tickersLive variable indicates whether it is required to keep updating the tickers variable. If this variable is false the tickers variable will not be updated. The tickersLive variable can be used to limit network traffic by switching off updating of the tickers variable when not required.

the tickersLive variable can be set through normal assignment.

radex.state.tickersLive = false;

The tickersLive$ variable is an Observable version of the tickersLive variable.

tickers / tickers$

tickers: Map<string, TimeSlice>;
tickers$: Observable<Map<string TimeSlice>>;

The tickers variable provides a Map of the 24h timeslices for all pairs on RaDEX. The Map is indexed by the code of the pair.

The tickers$ variable is an Observable version of the tickers variable.

RaDEX Types

The radex-js library provides a number of object types that conform to the data structure used by RaDEX.

Pair type

A Pair object represents a trading pair on RaDEX.

 Pair = {
    code: string = '',  // the code or symbol for the pair e.g. "BTC-XRD"
    token1: string = '',  // the code for the first token in the pair e.g. "BTC"
    token2: string = '',  // the code for the second token in the pair e.g. "XRD"
    token1Decimals: number = 0,  // the number of decimals of precision used for token1 in the pair e.g. 8
    token2Decimals: number = 0,  // the number of decimals of precision used for token2 in the pair e.g. 8
    liquidityFee: number = 0,  // the liquidity fee that is paid for trades in this pair e.g. 0.001
    platformFee: number = 0, // the platform fee that is charged for trades in this pair e.g. 0.0005
 }

Pair information is set on the RaDEX network when a pair is created.

Order type

An Order object represents an order on RaDEX. An order is the intention to buy or sell a token in a certain pair. When an order is matched with another order, it becomes a Trade (see Trade type)

 Order = {
    id: string = '',  // a unique id for the order - assigned by RaDEX
    owner: string = '',  // the id of the owner of this order (wallet that submitted the order)
    pair: string = '',  // the pair code that this order is for
    token1: string = '',  // token1 code of the pair
    token2: string = '',  // token2 code of the pair
    dateCreated: number = 0,  // date that the order was created in UTC milliseconds
    dateCompleted: number = 0,  // date that the order was completed in UTC milliseconds
    side: OrderSide = OrderSide.EMPTY,  // the side of the order (see *OrderSide* enum)
    type: OrderType = OrderType.EMPTY, // the type of the order (see *OrderType* enum)
    price: number = 0,  // the price for the order, specified as token2 value
    quantity: number = 0,  // the quanity for the order, specified in token1 value
    value: number = 0,  // the value of the order, specified as token2 value
    quantityFulfilled: number = 0, // the quantity that has already been fulfilled for this order
    valueFulfilled: number = 0,  // the value that has already been fulfilled for this order
    quantitySpecified: boolean = true, // whether this order has specified a quantity or value to be fulfilled
    status: OrderStatus = OrderStatus.EMPTY, // the latest status of the order (see *OrderStatus* enum)
 }

New orders can be created using the submitOrder order function (see submitOrder function).

Trade type

A Trade object represents a completed trade on RaDEX. A trade is created when two orders partially or fully match each other (see Order type).

 Trade = {
    id: string = '',  // unique id for the trade
    pair: string = '',  // the pair that this trade relates to
    buyer: string = '',  // the buyer id for this trade
    buyOrderId: string = '',  // the buy order id
    seller: string = '',  // the seller id for this trade
    sellOrderId: string = '',  // the sell order id
    token1: string = '',  // code of token1 of the pair
    token2: string = '',  // code of token2 of the pair
    quantity: number = 0,  // quantity of token1 that was traded
    price: number = 0,  // quantity of token2 that was traded
    feePayer: TradeFeePayer,  // who was responsible for paying the fee on this trade (see *TradeFeePayer* enum)
    feeToken: string,  // the code for the token that the fee was paid in - either token1 or token2 code
    liquidityFee: number, // the total liquidity fee that was paid on the trade
    platformFee: number,  // the total platform fee that paid on the trade
    date: number, // the date of the trade in UTC milliseconds
    parties: string[],  // the buyer and seller ids
 }

TimeSlice type

A TimeSlice object represents a the summarised trade data for a certain period. This information is typically used in candle stick charts.

 TimeSlice = {
    startTime: number,  // the start time of this slice in UTC milliseconds
    pair: string,  // the pair that this slice relates to
    open: number,  // the price of the opening trade in this slice
    close: number,  // the price of the closing trade in this slice
    high: number, // the highest traded price in this slice,
    low: number,  // the lowest traded price in this slice
    token1Volume: number,  // the volume of token1 traded in this slice
    token2Volume: number,  // the volume of token2 traded in this slice
    noOfTrades: number,  // the number of trades in this slice
 }

RaDEX enums

Enums are specified values for certain object variables. The variables must be set to one of these values. radex-js provides access to the enums to help developers set the right vlaues for these variables.

OrderSide enum

The OrderSide enum specifies the sides that an order can be.

enum OrderSide {
  EMPTY = '',
  BUY = 'BUY',
  SELL = 'SELL',
}

OrderType enum

The OrderType enum specifies the types that an order can be.

enum OrderType {
  EMPTY = '',
  MARKET = 'MARKET',
  LIMIT = 'LIMIT',
  LIMITONLY = 'LIMIT-ONLY',
}

OrderStatus enum

The OrderStatus enum specifies the statuses that an order can be in.

enum OrderStatus {
  EMPTY = '',
  SUBMITTING = 'SUBMITTING', // order has been added to queue, but not yet processed
  PENDING = 'PENDING', // order has been added to order book, awaiting fulfilment
  COMPLETED = 'COMPLETED', // order has been fulfilled
  CANCELLED = 'CANCELLED', // order has been cancelled by owner
}

TradeFeePayer enum

The TradeFeePayer enum specifies which of the buyer or seller in a trade is responsible for paying the fees.

enum TradeFeePayer {
  EMPTY = '',
  BUYER = 'BUYER',
  SELLER = 'SELLER',
}