Market Data

MarketData ⇐ PerpetualDataHandler

Functions to access market data (e.g., information on open orders, information on products that can be traded). This class requires no private key and is blockchain read-only. No gas required for the queries here.

Kind: global class Extends: PerpetualDataHandler

  • MarketData ⇐ PerpetualDataHandler

    • new MarketData(config)

    • .createProxyInstance(providerOrMarketData)

    • .getProxyAddress() ⇒ string

    • .getTriangulations() ⇒

    • .smartContractOrderToOrder(smOrder) ⇒ Order

    • .getReadOnlyProxyInstance() ⇒ Contract

    • .exchangeInfo() ⇒ ExchangeInfo

    • .openOrders(traderAddr, symbol) ⇒

    • .positionRisk(traderAddr, symbol) ⇒ Array.<MarginAccount>

    • .positionRiskOnTrade(traderAddr, order, account, indexPriceInfo) ⇒

    • .positionRiskOnCollateralAction(deltaCollateral, account) ⇒ MarginAccount

    • .getWalletBalance(address, symbol) ⇒

    • .getPoolShareTokenBalance(address, symbolOrId) ⇒ number

    • .getShareTokenPrice(symbolOrId) ⇒ number

    • .getParticipationValue(address, symbolOrId) ⇒

    • .maxOrderSizeForTrader(traderAddr, symbol) ⇒

    • .maxSignedPosition(side, symbol) ⇒ number

    • .getOraclePrice(base, quote) ⇒ number

    • .getOrderStatus(symbol, orderId, overrides) ⇒

    • .getOrdersStatus(symbol, orderId) ⇒

    • .getMarkPrice(symbol) ⇒ number

    • .getPerpetualPrice(symbol, quantity) ⇒ number

    • .getPerpetualState(symbol) ⇒ PerpetualState

    • .getPoolState(poolSymbol) ⇒ PoolState

    • .getPerpetualStaticInfo(symbol) ⇒ PerpetualStaticInfo

    • .getPerpetualMidPrice(symbol) ⇒ number

    • .getAvailableMargin(traderAddr, symbol, indexPrices) ⇒

    • .getTraderLoyalityScore(traderAddr) ⇒ number

    • .isMarketClosed(symbol) ⇒ boolean

    • .getPriceInUSD(symbol) ⇒ Map.<string, number>

    • .fetchPricesForPerpetual(symbol) ⇒

new MarketData(config)

Constructor

Param
Type
Description

config

NodeSDKConfig

Configuration object, see PerpetualDataHandler.readSDKConfig.

Example

import { MarketData, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(MarketData);
  // load configuration for Polygon zkEVM (testnet)
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  // MarketData (read only, no authentication needed)
  let mktData = new MarketData(config);
  // Create a proxy instance to access the blockchain
  await mktData.createProxyInstance();
}
main();

marketData.createProxyInstance(providerOrMarketData)

Initialize the marketData-Class with this function to create instance of D8X perpetual contract and gather information about perpetual currencies

Kind: instance method of MarketData

Param
Description

providerOrMarketData

optional provider or existing market data instance

marketData.getProxyAddress() ⇒ string

Get the proxy address

Kind: instance method of MarketData Returns: string -

Address of the perpetual proxy contract

marketData.getTriangulations() ⇒

Get the pre-computed triangulations

Kind: instance method of MarketData Returns:

Triangulations

marketData.smartContractOrderToOrder(smOrder) ⇒ Order

Convert the smart contract output of an order into a convenient format of type "Order"

Kind: instance method of MarketData Returns: Order -

more convenient format of order, type "Order"

Param
Type
Description

smOrder

SmartContractOrder

SmartContractOrder, as obtained e.g., by PerpetualLimitOrderCreated event

marketData.getReadOnlyProxyInstance() ⇒ Contract

Get contract instance. Useful for event listening.

Kind: instance method of MarketData Returns: Contract -

read-only proxy instance

Example

import { MarketData, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(MarketData);
  // setup
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  let mktData = new MarketData(config);
  await mktData.createProxyInstance();
  // Get contract instance
  let proxy = await mktData.getReadOnlyProxyInstance();
  console.log(proxy);
}
main();

marketData.exchangeInfo() ⇒ ExchangeInfo

Information about the products traded in the exchange.

Kind: instance method of MarketData Returns: ExchangeInfo -

Array of static data for all the pools and perpetuals in the system.

Example

import { MarketData, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(MarketData);
  // setup
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  let mktData = new MarketData(config);
  await mktData.createProxyInstance();
  // Get exchange info
  let info = await mktData.exchangeInfo();
  console.log(info);
}
main();

marketData.openOrders(traderAddr, symbol) ⇒

All open orders for a trader-address and a symbol.

Kind: instance method of MarketData Returns:

For each perpetual an array of open orders and corresponding order-ids.

Param
Type
Description

traderAddr

string

Address of the trader for which we get the open orders.

symbol

string

Symbol of the form ETH-USD-MATIC or a pool symbol, or undefined. If a poolSymbol is provided, the response includes orders in all perpetuals of the given pool. If no symbol is provided, the response includes orders from all perpetuals in all pools.

Example

import { MarketData, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(MarketData);
  // setup
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  let mktData = new MarketData(config);
  await mktData.createProxyInstance();
  // Get all open orders for a trader/symbol
  let opOrder = await mktData.openOrders("0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B",
      "ETH-USD-MATIC");
  console.log(opOrder);
}
main();

marketData.positionRisk(traderAddr, symbol) ⇒ Array.<MarginAccount>

Information about the position open by a given trader in a given perpetual contract, or for all perpetuals in a pool

Kind: instance method of MarketData Returns: Array.<MarginAccount> -

Array of position risks of trader.

Param
Type
Description

traderAddr

string

Address of the trader for which we get the position risk.

symbol

string

Symbol of the form ETH-USD-MATIC, or pool symbol ("MATIC") to get all positions in a given pool, or no symbol to get all positions in all pools.

Example

import { MarketData, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(MarketData);
  // setup
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  let mktData = new MarketData(config);
  await mktData.createProxyInstance();
  // Get position risk info
  let posRisk = await mktData.positionRisk("0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B",
      "ETH-USD-MATIC");
  console.log(posRisk);
}
main();

marketData.positionRiskOnTrade(traderAddr, order, account, indexPriceInfo) ⇒

Estimates what the position risk will be if a given order is executed.

Kind: instance method of MarketData Returns:

Position risk after trade, including order cost and maximal trade sizes for position

Param
Description

traderAddr

Address of trader

order

Order to be submitted

account

Position risk before trade. Defaults to current position if not given.

indexPriceInfo

Index prices and market status (open/closed). Defaults to current market status if not given.

Example

import { MarketData, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(MarketData);
  // setup
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  const mktData = new MarketData(config);
  await mktData.createProxyInstance();
  const order: Order = {
       symbol: "MATIC-USD-MATIC",
       side: "BUY",
       type: "MARKET",
       quantity: 100,
       leverage: 2,
       executionTimestamp: Date.now()/1000,
   };
  // Get position risk conditional on this order being executed
  const posRisk = await mktData.positionRiskOnTrade("0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B", order);
  console.log(posRisk);
}
main();

marketData.positionRiskOnCollateralAction(deltaCollateral, account) ⇒ MarginAccount

Estimates what the position risk will be if given amount of collateral is added/removed from the account.

Kind: instance method of MarketData Returns: MarginAccount -

Position risk after collateral has been added/removed

Param
Type
Description

deltaCollateral

number

Amount of collateral to add or remove (signed)

account

MarginAccount

Position risk before collateral is added or removed

Example

import { MarketData, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(MarketData);
  // setup
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  const mktData = new MarketData(config);
  await mktData.createProxyInstance();
  // Get position risk conditional on removing 3.14 MATIC
  const traderAddr = "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B";
  const curPos = await mktData.positionRisk("traderAddr", "BTC-USD-MATIC");
  const posRisk = await mktData.positionRiskOnCollateralAction(-3.14, curPos);
  console.log(posRisk);
}
main();

marketData.getWalletBalance(address, symbol) ⇒

Gets the wallet balance in the collateral currency corresponding to a given perpetual symbol.

Kind: instance method of MarketData Returns:

Perpetual's collateral token balance of the given address.

Param
Description

address

Address to check

symbol

Symbol of the form ETH-USD-MATIC.

Example

import { MarketData, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(MarketData);
  // setup (authentication required, PK is an environment variable with a private key)
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  let md = new MarketData(config);
  await md.createProxyInstance();
  // get MATIC balance of address
  let marginTokenBalance = await md.getWalletBalance(myaddress, "BTC-USD-MATIC");
  console.log(marginTokenBalance);
}
main();

marketData.getPoolShareTokenBalance(address, symbolOrId) ⇒ number

Get the address' balance of the pool share token

Kind: instance method of MarketData Returns: number -

Pool share token balance of the given address (e.g. dMATIC balance)

Param
Type
Description

address

string

address of the liquidity provider

symbolOrId

string | number

Symbol of the form ETH-USD-MATIC, or MATIC (collateral only), or Pool-Id

Example

import { MarketData, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(MarketData);
  // setup (authentication required, PK is an environment variable with a private key)
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  let md = new MarketData(config);
  await md.createProxyInstance();
  // get dMATIC balance of address
  let shareTokenBalance = await md.getPoolShareTokenBalance(myaddress, "MATIC");
  console.log(shareTokenBalance);
}
main();

marketData.getShareTokenPrice(symbolOrId) ⇒ number

Value of pool token in collateral currency

Kind: instance method of MarketData Returns: number -

current pool share token price in collateral currency

Param
Type
Description

symbolOrId

string | number

symbol of the form ETH-USD-MATIC, MATIC (collateral), or poolId

Example

import { MarketData, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(MarketData);
  // setup (authentication required, PK is an environment variable with a private key)
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  let md = new MarketData(config);
  await md.createProxyInstance();
  // get price of 1 dMATIC in MATIC
  let shareTokenPrice = await md.getShareTokenPrice(myaddress, "MATIC");
  console.log(shareTokenPrice);
}
main();

marketData.getParticipationValue(address, symbolOrId) ⇒

Value of the pool share tokens for this liquidity provider in poolSymbol-currency (e.g. MATIC, USDC).

Kind: instance method of MarketData Returns:

the value (in collateral tokens) of the pool share, #share tokens, shareTokenAddress

Param
Type
Description

address

string

address of liquidity provider

symbolOrId

string | number

symbol of the form ETH-USD-MATIC, MATIC (collateral), or poolId

Example

import { MarketData, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(MarketData);
  // setup (authentication required, PK is an environment variable with a private key)
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  let md = new MarketData(config);
  await md.createProxyInstance();
  // get value of pool share token
  let shareToken = await md.getParticipationValue(myaddress, "MATIC");
  console.log(shareToken);
}
main();

marketData.maxOrderSizeForTrader(traderAddr, symbol) ⇒

Gets the maximal order sizes to open positions (increase size), both long and short, considering the existing position, state of the perpetual Accounts for user's wallet balance.

Kind: instance method of MarketData Returns:

Maximal trade sizes

Param
Type
Description

traderAddr

string

Address of trader

symbol

symbol

Symbol of the form ETH-USD-MATIC

Example

import { MarketData, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(MarketData);
  // setup (authentication required, PK is an environment variable with a private key)
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  let md = new MarketData(config);
  await md.createProxyInstance();
  // max order sizes
  let shareToken = await md.maxOrderSizeForTrader(myaddress, "BTC-USD-MATIC");
  console.log(shareToken); // {buy: 314, sell: 415}
}
main();

marketData.maxSignedPosition(side, symbol) ⇒ number

Perpetual-wide maximal signed position size in perpetual.

Kind: instance method of MarketData Returns: number -

signed maximal position size in base currency

Param
Type
Description

side

BUY_SIDE or SELL_SIDE

symbol

string

of the form ETH-USD-MATIC.

Example

import { MarketData, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(MarketData);
  // setup
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  let mktData = new MarketData(config);
  await mktData.createProxyInstance();
  // get oracle price
  let maxLongPos = await mktData.maxSignedPosition(BUY_SIDE, "BTC-USD-MATIC");
  console.log(maxLongPos);
}
main();

marketData.getOraclePrice(base, quote) ⇒ number

Uses the Oracle(s) in the exchange to get the latest price of a given index in a given currency, if a route exists.

Kind: instance method of MarketData Returns: number -

Price of index in given currency.

Param
Type
Description

base

string

Index name, e.g. ETH.

quote

string

Quote currency, e.g. USD.

Example

import { MarketData, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(MarketData);
  // setup
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  let mktData = new MarketData(config);
  await mktData.createProxyInstance();
  // get oracle price
  let price = await mktData.getOraclePrice("ETH", "USD");
  console.log(price);
}
main();

marketData.getOrderStatus(symbol, orderId, overrides) ⇒

Get the status of an order given a symbol and order Id

Kind: instance method of MarketData Returns:

Order status (cancelled = 0, executed = 1, open = 2, unkown = 3)

Param
Description

symbol

Symbol of the form ETH-USD-MATIC

orderId

Order Id

overrides

Example

import { MarketData, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(MarketData);
  // setup
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  let mktData = new MarketData(config);
  await mktData.createProxyInstance();
  // get order stauts
  let status = await mktData.getOrderStatus("ETH-USD-MATIC", "0xmyOrderId");
  console.log(status);
}
main();

marketData.getOrdersStatus(symbol, orderId) ⇒

Get the status of an array of orders given a symbol and their Ids

Kind: instance method of MarketData Returns:

Array of order status

Param
Description

symbol

Symbol of the form ETH-USD-MATIC

orderId

Array of order Ids

Example

import { MarketData, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(MarketData);
  // setup
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  let mktData = new MarketData(config);
  await mktData.createProxyInstance();
  // get order stauts
  let status = await mktData.getOrdersStatus("ETH-USD-MATIC", ["0xmyOrderId1", "0xmyOrderId2"]);
  console.log(status);
}
main();

marketData.getMarkPrice(symbol) ⇒ number

Get the current mark price

Kind: instance method of MarketData Returns: number -

mark price

Param
Description

symbol

symbol of the form ETH-USD-MATIC

Example

import { MarketData, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(MarketData);
  // setup
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  let mktData = new MarketData(config);
  await mktData.createProxyInstance();
  // get mark price
  let price = await mktData.getMarkPrice("ETH-USD-MATIC");
  console.log(price);
}
main();

marketData.getPerpetualPrice(symbol, quantity) ⇒ number

get the current price for a given quantity

Kind: instance method of MarketData Returns: number -

price

Param
Description

symbol

symbol of the form ETH-USD-MATIC

quantity

quantity to be traded, negative if short

Example

import { MarketData, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(MarketData);
  // setup
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  let mktData = new MarketData(config);
  await mktData.createProxyInstance();
  // get perpetual price
  let price = await mktData.getPerpetualPrice("ETH-USD-MATIC", 1);
  console.log(price);
}
main();

marketData.getPerpetualState(symbol) ⇒ PerpetualState

Query recent perpetual state from blockchain

Kind: instance method of MarketData Returns: PerpetualState -

PerpetualState copy

Param
Type
Description

symbol

string

symbol of the form ETH-USD-MATIC

marketData.getPoolState(poolSymbol) ⇒ PoolState

Query recent pool state from blockchain, not including perpetual states

Kind: instance method of MarketData Returns: PoolState -

PoolState copy

Param
Type
Description

poolSymbol

string

symbol of the form USDC

marketData.getPerpetualStaticInfo(symbol) ⇒ PerpetualStaticInfo

Query perpetual static info. This information is queried once at createProxyInstance-time, and remains static after that.

Kind: instance method of MarketData Returns: PerpetualStaticInfo -

Perpetual static info copy.

Param
Type
Description

symbol

string

Perpetual symbol

marketData.getPerpetualMidPrice(symbol) ⇒ number

get the current mid-price for a perpetual

Kind: instance method of MarketData Returns: number -

price

Param
Description

symbol

symbol of the form ETH-USD-MATIC

Example

import { MarketData, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(MarketData);
  // setup
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  let mktData = new MarketData(config);
  await mktData.createProxyInstance();
  // get perpetual mid price
  let midPrice = await mktData.getPerpetualMidPrice("ETH-USD-MATIC");
  console.log(midPrice);
}
main();

marketData.getAvailableMargin(traderAddr, symbol, indexPrices) ⇒

Query the available margin conditional on the given (or current) index prices Result is in collateral currency

Kind: instance method of MarketData Returns:

available margin in collateral currency

Param
Type
Description

traderAddr

string

address of the trader

symbol

string

perpetual symbol of the form BTC-USD-MATIC

indexPrices

optional index prices, will otherwise fetch from REST API

Example

import { MarketData, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(MarketData);
  // setup
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  let mktData = new MarketData(config);
  await mktData.createProxyInstance();
  // get available margin
  let mgn = await mktData.getAvailableMargin("0xmyAddress", "ETH-USD-MATIC");
  console.log(mgn);
}
main();

marketData.getTraderLoyalityScore(traderAddr) ⇒ number

Calculate a type of exchange loyality score based on trader volume

Kind: instance method of MarketData Returns: number -

a loyality score (4 worst, 1 best)

Param
Type
Description

traderAddr

string

address of the trader

Example

import { MarketData, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(MarketData);
  // setup
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  let mktData = new MarketData(config);
  await mktData.createProxyInstance();
  // get scpre
  let s = await mktData.getTraderLoyalityScore("0xmyAddress");
  console.log(s);
}
main();

marketData.isMarketClosed(symbol) ⇒ boolean

Get market open/closed status

Kind: instance method of MarketData Returns: boolean -

True if the market is closed

Param
Type
Description

symbol

string

Perpetual symbol of the form ETH-USD-MATIC

Example

import { MarketData, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(MarketData);
  // setup
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  let mktData = new MarketData(config);
  await mktData.createProxyInstance();
  // is market closed?
  let s = await mktData.isMarketClosed("ETH-USD-MATIC");
  console.log(s);
}
main();

marketData.getPriceInUSD(symbol) ⇒ Map.<string, number>

Get the latest on-chain price of a perpetual base index in USD.

Kind: instance method of MarketData Returns: Map.<string, number> -

Price of the base index in USD, e.g. for ETH-USDC-MATIC, it returns the value of ETH-USD.

Param
Type
Description

symbol

string

Symbol of the form ETH-USDC-MATIC. If a pool symbol is used, it returns an array of all the USD prices of the indices in the pool. If no argument is provided, it returns all prices of all the indices in the pools of the exchange.

Example

import { MarketData, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(MarketData);
  // setup
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  let mktData = new MarketData(config);
  await mktData.createProxyInstance();
  // is market closed?
  let px = await mktData.getPriceInUSD("ETH-USDC-USDC");
  console.log(px); // {'ETH-USD' -> 1800}
}
main();

marketData.fetchPricesForPerpetual(symbol) ⇒

Fetch latest off-chain index and collateral prices

Kind: instance method of MarketData Returns:

Prices and market-closed information

Param
Description

symbol

Perpetual symbol of the form BTC-USDc-USDC