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

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

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"

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.

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.

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

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

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.

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)

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

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

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

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

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.

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)

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

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

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

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

marketData.getPoolState(poolSymbol) ⇒ PoolState

Query recent pool state from blockchain, not including perpetual states

Kind: instance method of MarketData Returns: PoolState -

PoolState copy

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.

marketData.getPerpetualMidPrice(symbol) ⇒ number

get the current mid-price for a perpetual

Kind: instance method of MarketData Returns: number -

price

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

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)

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

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.

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