@electra.finance/sdk v0.2.22

Overview

Electra Software Developer Kit is a futures trading library for JavaScript and TypeScript. It provides a set of tools for building trading bots, price feeds, and other applications on top of Electra Finance.

API Key

Electra’s SDK is free to use and does not require an API key or registration. Refer to integration examples for more detailed information.

• Overview
• API Key
• Install
• Usage
• Initialization
• Crosschain methods
  • Get pairs
• Chain-specific methods
  • Deposit and withdraw
  • Get aggregated orderbook
  • Get historical price
  • Get tradable pairs
  • Get deposits and withdrawals
  • Get available contracts
  • Place order
  • Aggregator WebSocket
  • Balances and order history stream
  • Orderbook stream
  • Aggregator WS Stream Unsubscribing
• Price Feed Websocket Stream
• Data fetching
• Using contracts

Install

npm i @electra.finance/sdk

Usage

Initialization

:warning: Ethers ^5.6.0 required

// Node.js
import { Unit, Electra } from "@electra.finance/sdk";
import { Wallet } from "ethers";

const electra = new Electra();
const unit = electra.getUnit("bsc"); // eth, bsc, ftm, polygon, okc available
const wallet = new Wallet("0x...", unit.provider);
// Unit is chain-in-environment abstraction

// Metamask
import { Unit } from "@electra.finance/sdk";
import detectEthereumProvider from "@metamask/detect-provider";
import { BaseProvider } from "@metamask/providers";
import { providers } from "ethers";

const startApp = async (provider: BaseProvider) => {
  const web3Provider = new providers.Web3Provider(provider);
  await web3Provider.ready;
  const signer = web3Provider.getSigner(); // ready to go
  const electra = new Electra();
  const unit = electra.getUnit("eth"); // ready to go
};

detectEthereumProvider().then((provider) => {
  if (provider) {
    startApp(provider as BaseProvider);
  } else {
    console.log("Please install MetaMask!");
  }
});

Crosschain methods

Get pairs

const pairs = await electra.getPairs("futures"); // 'futures'

// Response example:
// {
//   'BTCUSDF': [ '1', '56' ],
//   'ETHUSDF': [ '1', '56', '137' ],
// }

Chain-specific methods

Deposit and withdraw

To make deposits and withdrawals, you need to use package @electra.finance/contracts.

import { IsolatedMarginCFD__factory } from "@electra.finance/contracts";

const cfdContractAddress = "0x0000000000000000000000000000000000000000";
const cfdContract = IsolatedMarginCFD__factory.connect(cfdContractAddress, signer);

const deposit = await cfdContract.depositAsset("12423450000"); // Deposit
const withdraw = await cfdContract.withdrawAsset("12423450000"); // Withdraw

Get aggregated orderbook

import { simpleFetch } from "simple-typed-fetch";

const orderbook = await simpleFetch(unit.aggregator.getAggregatedOrderbook)(
  "BTCUSDF",
  20 // Depth
);

Get historical price

import { simpleFetch } from "simple-typed-fetch";

const candles = await simpleFetch(unit.priceFeed.getCandles)(
  "BTCUSDF",
  1650287678, // interval start, unix timestamp
  1650374078, // interval end, unix timestamp
  "5m" // '5m' or '30m' or '1h' or '1d',
);

Get tradable pairs

import { simpleFetch } from "simple-typed-fetch";
const pairsList = await simpleFetch(unit.aggregator.getPairsList)("futures");
console.log(pairsList); // ['ETHUSDF, 'BTCUSDF']

Get deposits and withdrawals

import { simpleFetch } from "simple-typed-fetch";
const depositsAndWithdrawals = await simpleFetch(unit.blockchainService.getCFDHistory)(
  "0x0000000000000000000000000000000000000000", // Some wallet address
);
console.log(depositsAndWithdrawals);

Get available contracts

import { simpleFetch } from "simple-typed-fetch";
const contracts = await simpleFetch(unit.blockchainService.getCFDContracts)();
console.log(contracts);

Place order

import { simpleFetch } from "simple-typed-fetch";
import { signCFDOrder } from "@electra.finance/sdk";

const {
  matcherAddress, // The address that will transfer funds to you during the exchange process
} = await simpleFetch(unit.blockchainService.getInfo)();

const signedOrder = signCFDOrder(
  "0x0000000000000000000000000000000000000000", // instrumentAddress, you can retrieve list of available instruments from blockchainService.getCFDContracts()
  'BUY', // side: 'BUY' | 'SELL'
  "0.34543", // price
  "245234.234", // amount
  "matcherFee", // matcherFee
  "0xfffffffffffffffffffffffffffffffffffffff", // senderAddress
  matcherAddress,
  false, // usePersonalSign
  signer, // pass here ethers.Signer instance
  chainId: SupportedChainId.BSC,
  "0.34", // optional stopPrice
  false // isFromDelegate — if true, then the order will be placed on behalf of the delegate
);

const { orderId } =  = await simpleFetch(unit.aggregator.placeCFDOrder)(signedOrder);
console.log(`Order placed: ${orderId}`);

Aggregator WebSocket

Available subscriptions:

CFD_ADDRESS_UPDATES_SUBSCRIBE = 'ausf', // Orders history, positions info, balances info
AGGREGATED_ORDER_BOOK_UPDATES_SUBSCRIBE = 'aobus', // Bids and asks

Balances and order history stream

unit.aggregator.ws.subscribe(
  "ausf", // CFD_ADDRESS_UPDATES_SUBSCRIBE — orders, positions, balances
  {
    payload: "0x0000000000000000000000000000000000000000", // Some wallet address
    callback: (data) => {
      switch (data.kind) {
        case "initial":
          if (data.orders) console.log(data.orders); // All orders. "orders" is undefined if you don't have any orders yet
          if (data.balances) console.log(data.balances); // All balances
          break;
        case "update": {
          if (data.orders) console.log("Order update", data.orders); // Since this is an update message, the orders only contain the changed orders
          if (data.balances) console.log("Balance update", data.balances); // Since this is an update message, the balances only contain the changed assets
        }
      }
    },
  }
);

unit.aggregator.ws.unsubscribe("0x0000000000000000000000000000000000000000");

Orderbook stream

unit.aggregator.ws.subscribe("aobus", {
  payload: "ETHUSDF", // Some trading pair
  callback: (asks, bids, pairName) => {
    console.log(`${pairName} orderbook asks`, asks);
    console.log(`${pairName} orderbook bids`, bids);
  },
});

unit.aggregator.ws.unsubscribe("ETHUSDF");

Aggregator WS Stream Unsubscribing

// Asset pairs config updates unsubscribe
unit.aggregator.ws.unsubscribe("apcu");

Price Feed Websocket Stream

const allTickersSubscription = unit.priceFeed.ws.subscribe("allTickers", {
  callback: (tickers) => {
    console.log(tickers);
  },
});
allTickersSubscription.unsubscribe();
unit.priceFeed.ws.unsubscribe("allTickers", allTickersSubscription.id); // Also you can unsubscribe like this

const tickerSubscription = unit.priceFeed.ws.subscribe("ticker", {
  callback: (ticker) => {
    console.log(tricker);
  },
  payload: "ETHUSDF",
});
tickerSubscription.subscription();
unit.priceFeed.ws.unsubscribe("ticker", tickerSubscription.id);

const lastPriceSubscription = unit.priceFeed.ws.subscribe("lastPrice", {
  callback: ({ pair, price }) => {
    console.log(`Price: ${price}`);
  },
  payload: "ETHUSDF",
});
lastPriceSubscription.unsubscribe();
unit.priceFeed.ws.unsubscribe("lastPrice", lastPriceSubscription.id);

Data fetching

// Verbose way example

const getCandlesResult = await unit.priceFeed.getCandles(
  "ETHUSDF",
  1650287678,
  1650374078,
  "5m"
);
if (getCandlesResult.isErr()) {
  // You can handle fetching errors here
  // You can access error text, statuses
  const { error } = placeOrderFetchResult;
  switch (error.type) {
    case "fetchError": // Instance of Error
      console.error(error.message);
      break;
    case "unknownFetchError":
      console.error(`URL: ${error.url}, Error: ${error.message}`);
      break;
    case "unknownFetchThrow":
      console.error("Something wrong happened during fetching", error.error);
      break;
    // ... more error types see in src/fetchWithValidation.ts
  }
} else {
  // Success result
  const { candles, timeStart, timeEnd } = getCandlesResult.value;
  // Here we can handle response data
}

// Simple Fetch

const { candles, timeStart, timeEnd } = await simpleFetch(
  unit.priceFeed.getCandles
)("ETHUSDF", 1650287678, 1650374078, "5m");

// Here we can handle response data

Using contracts

Use package @electra.finance/contracts