alphadex-sdk-js v0.12.14

alphadex-sdk-js (AlphaDEX Javascript SDK)

alphadex-sdk-js is a typescript/javascript package to help developers integrate effortlessly with the AlphaDEX decentralised exchange on Radix DLT

It provides developers with easy access to the live data on the AlphaDEX exchange as well as a number of convenience functions and classes/types for working with the exchange.

Interesting note: alphadex-sdk-js connects to the AlphaDEX Websocket server to provide the live data feed without any intervention needed from the developer.

Installation

Node.js and NPM

You will need node.js and npm (node package manager) installed on your machine in order to add alphadex-sdk-js to your project. If you do not yet have it installed, you can find instructions to do so here

Add alphadex-sdk-js to your project

To add alphadex-sdk-js to your project, run the following command from the root directory of your project:

npm install --save alphadex-sdk-js

Updating the SDK

Update to latest patch (non-breaking changes)

To update the SDK for any new changes that are non-breaking (either bug fixes or feature additions), you can run the following command in your project directory:

npm update alphadex-sdk-js

Update to latest version (including breaking changes)

To update the SDK to the very latest version (which might include breaking changes), you can run the following command in your project directory:

npm install --save alphadex-sdk-js@latest

Usage

Import required variables and functions

To use alphadex-sdk-js in your project, you need to import at least the init function and the clientState object. You will need to import and run the init function in the first file that executes (e.g. index.js).

For ease of use it is suggested to import all the alphadex-sdk-js functions and variables as one combined reference (e.g. adex, but you can choose any name). This has the benefit that it clearly distinguishes the AlphaDEX SDK functions from your app's own native functions and will provide auto-complete functionality in your editor to help you choose the appropraite function.

Example: Import all AlphaDEX SDK functions and variables as one reference called adex.

import * as adex from "alphadex-sdk-js";

Alternatively you can import each function and variable individually.

Example: Import functions and variables individually.

import { init, clientState } from "alphadex-sdk-js";

Initialize the AlphaDEX SDK

In order to connect the AlphaDEX SDK to the live data on the AlphaDEX exchange you need to run the init function in the root file of your project (e.g. index.js). This function will connect to the AlphaDEX websocket server and ensure that the sdk variables are kept in sync with the live data on the exchange.

Example: Run the init function to initialize the sdk connection with the AlphaDEX exchange (using combined import as adex).

// import all the sdk functions and variables as adex
import * as adex from "alphadex-sdk-js";
...
// run the sdk init function to establish a live connection with the exchange
adex.init();

// use the variables with the live data in your program/app
let adexState = adex.clientState;
console.log("Status of the alphadex sdk connection: "+adexState.status);

Example: Run the init function to initialize the sdk connection with the AlphaDEX exchange (using individual imports).

// import init function and clientState variable individually
import { clientState, init } from "alphadex-sdk-js";
...
// run the sdk init function to establish a live connection with the exchange
init();

// use the variables with the live data in your program/app
let adexState = clientState;
console.log("Status of the alphadex sdk connection: "+adexState.status);

Using variables in alphadex-sdk-js

alphadex-sdk-js gives the developer access to a number of variables that are constantly updated to reflect the latest state of the AlphaDEX exchange.

All variables have a static and observable version (indicated by a $ at the end of the variable name).

Example: static and observable version of a variable

let staticStatus = adex.clientState.status;
let observableStatus = adex.clientState.status$;

All these variables are provided in one object called clientState.

clientState object

The clientState object holds all variables that reflect the live state of the AlphaDEX exchange. This object must be initialized by calling the init function.

Example: Calling the init function to initialize the clientState object and assigning the clientState object to a local variable myAdexState.

import * as adex from "alphadex-sdk-js";

// call the init function to connect to the AlphaDEX exchange
// and initialize the clientState object
adex.init();

// assign the clientState object to a local variable
let myAdexState = adex.clientState;

Variables

All the variables below are accessed as fields of the clientState object.

Example: How to access a variable.

// Accessing the status variable
let connectionStatus = adex.clientState.status

Read + Write Variables

These variables can be changed by the user. When the variables are changed they will automatically cause all related variables to update automatically.

Read Only Variables

Functions List

Setup Functions

Functions to initialize and destroy the SDK connection to the AlphaDEX exchange. | Function Name | Description | | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | init | Connects SDK to AlphaDEX exchange and initializes the clientState object. | | destroy | Stops SDK connection with AlphaDEX exchange and resets clientState object. |

Create Transaction Functions

Functions that create a transaction manifest that can be submitted to a user wallet for signing. | Function Name | Description | | ----------------------------------------------------------------------------------- | ----------- | | createCancelOrderTx | Create a transaction manifest for cancelling an exchange order. | | createExchangeOrderTx | Create a transaction manifest for an exchange order. | | createNewPlatformBadgeTx | Create a transaction manifest to create a new platform badge. | | createChangePlatformFeeTx | Create a transaction manifest to change the fee of a platform badge. | | createChangePlatformNameTx | Create a transaction manifest to change the name of a platform badge. | | createNewPairTx | Create a transaction manifest to create a new pair. | | createSwapTx | Create a transaction manifest for a swap. |

Submit Transaction Functions

Functions that submit a transaction directly to the user wallet for signing.

Get Data Functions

Functions that fetch AlphaDEX related data from a specific account or set of accounts or the ledger.

Get Quotes Functions

Functions that provide an estimated quote of tokens received and exchange costs for a planned order/swap. Useful to show a user the estimated outcome of an order/swap.

Functions Details

init() async function(#functions-list)

Function that connects the SDK to the AlphaDEX exchange websocket server and initializes the clientState object.

Parameters:

Returns: Promise of SDKResult

Successful SDKResult data field : nothing

destroy() (back to Functions List)

Function that disconnects the SDK from the AlphaDEX exchange websocket server and clears the clientState object.

It is suggested to call this function when a live connection to the AlphaDEX exchange is no longer needed or when the user exits your app.

Parameters: None

Returns: Nothing

getExchangeOrderQuote() async function(#functions-list)

Function that returns an estimated quote for a new AlphaDEX exchange order.

Parameters:

Returns: Promise of SDKResult

Successful SDKResult data field : Quote (Estimated outcome of the specified exchange transaction)

createExchangeOrderTx() async function(#functions-list)

Function to create a transaction manifest for creating a new AlphaDEX exchange order.

Parameters:

Returns: Promise of SDKResult

Successful SDKResult data field : string (The transaction manifest to be submitted by the user)

submitExchangeOrder() async function(#functions-list)

Function to submit a new AlphaDEX exchange order.

It will create the required transaction manifest and submit to the user's wallet for signing. After the transaction the user should see a new order receipt in their wallet with the details of the order as well as any changes in tokens as a result of the order.

Parameters:

Returns: Promise of SDKResult

Successful SDKResult data field : object (The transaction detail object returned by the Radix Gateway API)

createCancelOrderTx() async function(#functions-list)

Function to create a transaction manifest for cancelling an AlphaDEX exchange order.

Parameters:

Returns: Promise of SDKResult

Successful SDKResult data field : string (The transaction manifest to be submitted by the user)

submitCancelOrder() async function(#functions-list)

Function to cancel an AlphaDEX exchange order.

It will create the required transaction manifest and submit to the user's wallet for signing. After the transaction the user might see any unallocated tokens returned to their wallet and the order receipt should have a status of "CANCELLED".

Parameters:

Returns: Promise of SDKResult

Successful SDKResult data field : object (The transaction detail object returned by the Radix Gateway API)

getSwapQuote() async function(#functions-list)

Function that returns an estimated quote for a new AlphaDEX swap.

Parameters:

Returns: Promise of SDKResult

Successful SDKResult data field : string (The transaction manifest to be submitted by the user)

createSwapTx() async function(#functions-list)

Function to create a transaction manifest for creating a new AlphaDEX swap order.

Parameters:

Returns: Promise of SDKResult

Successful SDKResult data field : string (The transaction manifest to be submitted by the user)

submitSwap() async function(#functions-list)

Function to submit a new AlphaDEX swap order.

It will create the required transaction manifest and submit to the user's wallet for signing. After the transaction the user should see a new order receipt in their wallet with the details of the order as well as any changes in tokens as a result of the order.

Parameters:

Returns: Promise of SDKResult

Successful SDKResult data field : object (The transaction detail object returned by the Radix Gateway API)

createNewPairTx() async function(#functions-list)

Function to create a transaction manifest for creating a new AlphaDEX Pair.

Parameters:

Returns: Promise of SDKResult

Successful SDKResult data field : string (The transaction manifest to be submitted by the user)

submitNewPairTx() async function(#functions-list)

Function for creating a new AlphaDEX pair. It will create the required transaction manifest and submit to the user's wallet for signing. Note that there is a cost of 500XRD to create a new pair.

Parameters:

Returns: Promise of SDKResult

Successful SDKResult data field : object (The transaction detail object returned by the Radix Gateway API)

createNewPlatformBadgeTx() async function(#functions-list)

Function to create a transaction manifest for creating a new AlphaDEX Platform Badge.

Parameters:

Returns: Promise of SDKResult

Successful SDKResult data field : string (The transaction manifest to be submitted by the user)

submitNewPlatformBadgeTx() async function(#functions-list)

Function for creating a new AlphaDEX Platform Badge. It will create the required transaction manifest and submit to the user's wallet for signing. After the transaction the user should see the new platform badge in their wallet.

Parameters:

Returns: Promise of SDKResult

Successful SDKResult data field : object (The transaction detail object returned by the Radix Gateway API)

createChangePlatformFeeTx() async function(#functions-list)

Function to create a transaction manifest for changing the fee on an AlphaDEX Platform Badge.

Parameters:

Returns: Promise of SDKResult

Successful SDKResult data field : string (The transaction manifest to be submitted by the user)

submitChangePlatformFeeTx() async function(#functions-list)

Function for changing the fee on an AlphaDEX Platform Badge. It will create the required transaction manifest and submit to the user's wallet for signing. After the transaction the user should see the new fee reflected in the data of the platform badge.

Parameters:

Returns: Promise of SDKResult

Successful SDKResult data field : object (The transaction detail object returned by the Radix Gateway API)

createChangePlatformNameTx() async function(#functions-list)

Function to create a transaction manifest for changing the platform name on an AlphaDEX Platform Badge.

Parameters:

Returns: Promise of SDKResult

Successful SDKResult data field : string (The transaction manifest to be submitted by the user)

submitChangePlatformNameTx() async function(#functions-list)

Function for changing the platform name on an AlphaDEX Platform Badge. It will create the required transaction manifest and submit to the user's wallet for signing. After the transaction the user should see the new platform name reflected in the data of the platform badge.

Parameters:

Returns: Promise of SDKResult

Successful SDKResult data field : object (The transaction detail object returned by the Radix Gateway API)

getAccountOrders() async function(#functions-list)

Function to fetch AlphaDEX orders for a specifc pair from an account.

Parameters: