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