Getting Started

Pre-requisites

In order to use the D8X Node SDK you will need to have TypeScript and Yarn installed:

Linux

• Install Node via nvm, see here
• Install Typescript:

  • $ npm install -g typescript

  • $ npm install -g ts-node

• Install Yarn, see here

Windows

• Install node.js with nvm-windows, see here
• Install yarn for the installed version of node you plan to use:

  • nvm use 18.12.1

    npm install -g yarn

• Install Typescript:

  • $ npm install -g typescript

  • $ npm install -g ts-node

Installation

You can install the SDK using NPM or Yarn to access the latest stable version of the package, or by cloning the repo in order to have access to experimental and state-of-the art developments in the D8X API. We recommend using Yarn.

Yarn

$ yarn add @d8x/perpetuals-sdk

NPM

$ npm install @d8x/perpetuals-sdk

Build from source

• Clone the official D8X Futures Node SDK repo
• Run yarn in the root directory of the repo to install the package

Initialization

Once the SDK is installed, import the modules you need from @d8x/d8x-futures-node-sdk:

//ts-node
import { MarketData, AccountTrade, PerpetualDataHandler } from '@d8x/perpetuals-sdk';

Read-only modules, such as MarketData, do not require you to specify a private key and can be instantiated without any additional user-provided data:

//ts-node
async function main() {
    // see what chain configurations are available:
    const configs = PerpetualDataHandler.getAvailableConfigs();
    console.log(configs);
    // output of the form:
    // Set(2) { '1101; zkevm', `196; xlayer'}
    
    // load configuration for xlayer
    const config = PerpetualDataHandler.readSDKConfig("xlayer");
    
    // MarketData (read only, no authentication needed)
    let mktData = new MarketData(config);
    
    // Create a proxy instance to access the blockchain
    await mktData.createProxyInstance();
    // now you can access all methods of the Market Data object
}
main();

Modules that require the user to cryptographically sign, such as AccountTrade that allows you to post orders on the blockchain, do require you to specify your private key. We recommend setting your private key as an environment variable, e.g. in a terminal prompt:

Linux/macOS

$ export PK="your-private-key-without-0x"

Windows

> set PK=your-private-key-without-0x

You can then instantiate modules with write-access as follows:

//ts-node
async function main() {
    // load configuration for ZKEVM cardona testnet
    const config = PerpetualDataHandler.readSDKConfig("cardona");
    
    // AccountTrade (authentication required)
    const pk: string = <string>process.env.PK;
    let accTrade = new AccountTrade(config, pk);
    
    // Create a proxy instance to access the blockchain
    await accTrade.createProxyInstance();
    // now you can access all methods of the Account Trade object
}
main();

Config

The D8X Node SDK package provides default configuration files and readSDKConfig accepts the choices "cardona" (for chainId 2442), "zkevm"(for chainId 1101), "x1" (for chainId 195) and "xlayer" (for chainId 196). The configuration file is required to initialize the node-package classes. There is most likely no reason to deviate from either of the default configuration files, but if you want you can, by providing a path to your configuration file:

//ts-node
// load bespoke configuration
const config = PerpetualDataHandler.readSDKConfig("../config/myConfig.json");