White-Label Partners

BrokerTool ⇐ WriteAccessHandler

Functions for white-label partners to determine fees, deposit lots, and sign-up traders. This class requires a private key and executes smart-contract interactions that require gas-payments.

Kind: global class Extends: WriteAccessHandler

• BrokerTool ⇐ WriteAccessHandler

  • new BrokerTool(config, privateKey, signer)

  • .getBrokerInducedFee(poolSymbolName) ⇒ number

  • .getFeeForBrokerDesignation(poolSymbolName, [lots]) ⇒ number

  • .getFeeForBrokerVolume(poolSymbolName) ⇒ number

  • .getFeeForBrokerStake([brokerAddr]) ⇒ number

  • .determineExchangeFee(order, traderAddr) ⇒ number

  • .getCurrentBrokerVolume(poolSymbolName) ⇒ number

  • .getLotSize(poolSymbolName) ⇒ number

  • .getBrokerDesignation(poolSymbolName) ⇒ number

  • .depositBrokerLots(poolSymbolName, lots) ⇒ ContractTransaction

  • .signOrder(order, traderAddr) ⇒ Order

  • .signSCOrder(scOrder, traderAddr) ⇒ string

  • .transferOwnership(poolSymbolName, newAddress) ⇒ ContractTransaction

new BrokerTool(config, privateKey, signer)

Constructor

Param	Type	Description
config	NodeSDKConfig	Configuration object, see PerpetualDataHandler. readSDKConfig.
privateKey	string	Private key of a white-label partner.
signer	Signer	Signer (ignored if a private key is provided)

Example

import { BrokerTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(BrokerTool);
  // load configuration for Polygon zkEVM (testnet)
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  // BrokerTool (authentication required, PK is an environment variable with a private key)
  const pk: string = <string>process.env.PK;
  let brokTool = new BrokerTool(config, pk);
  // Create a proxy instance to access the blockchain
  await brokTool.createProxyInstance();
}
main();

brokerTool.getBrokerInducedFee(poolSymbolName) ⇒ number

Determine the exchange fee based on lots, traded volume, and D8X balance of this white-label partner. This is the final exchange fee that this white-label partner can offer to traders that trade through him.

Kind: instance method of BrokerTool Returns: number -

Exchange fee for this white-label partner, in decimals (i.e. 0.1% is 0.001)

Param	Type	Description
poolSymbolName	string	Pool symbol name (e.g. MATIC, USDC, etc).

Example

import { BrokerTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(BrokerTool);
  // setup (authentication required, PK is an environment variable with a private key)
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  const pk: string = <string>process.env.PK;
  let brokTool = new BrokerTool(config, pk);
  await brokTool.createProxyInstance();
  // get white-label partner induced fee
  let brokFee = await brokTool.getBrokerInducedFee("MATIC");
  console.log(brokFee);
}
main();

brokerTool.getFeeForBrokerDesignation(poolSymbolName, [lots]) ⇒ number

Determine the exchange fee based on lots purchased by this white-label partner. The final exchange fee that this white-label partner can offer to traders that trade through him is equal to maximum(brokerTool.getFeeForBrokerDesignation(poolSymbolName), brokerTool.getFeeForBrokerVolume(poolSymbolName), brokerTool.getFeeForBrokerStake())

Kind: instance method of BrokerTool Returns: number -

Fee based solely on this white-label partner's designation, in decimals (i.e. 0.1% is 0.001).

Param	Type	Description
poolSymbolName	string	Pool symbol name (e.g. MATIC, USDC, etc).
[lots]	number	Optional, designation to use if different from this white-label partner's.

Example

import { BrokerTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(BrokerTool);
  // setup (authentication required, PK is an environment variable with a private key)
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  const pk: string = <string>process.env.PK;
  let brokTool = new BrokerTool(config, pk);
  await brokTool.createProxyInstance();
  // get white-label partner fee induced by lots
  let brokFeeLots = await brokTool.getFeeForBrokerDesignation("MATIC");
  console.log(brokFeeLots);
}
main();

brokerTool.getFeeForBrokerVolume(poolSymbolName) ⇒ number

Determine the exchange fee based on volume traded under this white-label partner. The final exchange fee that this white-label partner can offer to traders that trade through him is equal to maximum(brokerTool.getFeeForBrokerDesignation(poolSymbolName), brokerTool.getFeeForBrokerVolume(poolSymbolName), brokerTool.getFeeForBrokerStake())

Kind: instance method of BrokerTool Returns: number -

Fee based solely on a white-label partner's traded volume in the corresponding pool, in decimals (i.e. 0.1% is 0.001).

Param	Type	Description
poolSymbolName	string	Pool symbol name (e.g. MATIC, USDC, etc).

Example

import { BrokerTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(BrokerTool);
  // setup (authentication required, PK is an environment variable with a private key)
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  const pk: string = <string>process.env.PK;
  let brokTool = new BrokerTool(config, pk);
  await brokTool.createProxyInstance();
  // get white-label partner fee induced by volume
  let brokFeeVol = await brokTool.getFeeForBrokerVolume("MATIC");
  console.log(brokFeeVol);
}
main();

brokerTool.getFeeForBrokerStake([brokerAddr]) ⇒ number

Determine the exchange fee based on the current D8X balance in a white-label partner's wallet. The final exchange fee that this white-label partner can offer to traders that trade through him is equal to maximum(brokerTool.getFeeForBrokerDesignation(symbol, lots), brokerTool.getFeeForBrokerVolume(symbol), brokerTool.getFeeForBrokerStake)

Kind: instance method of BrokerTool Returns: number -

Fee based solely on a white-label partner's D8X balance, in decimals (i.e. 0.1% is 0.001).

Param	Type	Description
[brokerAddr]	string	Address of the white-label partner in question, if different from the one calling this function.

Example

import { BrokerTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(BrokerTool);
  // setup (authentication required, PK is an environment variable with a private key)
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  const pk: string = <string>process.env.PK;
  let brokTool = new BrokerTool(config, pk);
  await brokTool.createProxyInstance();
  // get white-label partner fee induced by staked d8x
  let brokFeeStake = await brokTool.getFeeForBrokerStake("0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B");
  console.log(brokFeeStake);
}
main();

brokerTool.determineExchangeFee(order, traderAddr) ⇒ number

Determine exchange fee based on an order and a trader. This is the fee charged by the exchange only, excluding the white-label partner fee, and it takes into account whether the order given here has been signed by a white-label partner or not. Use this, for instance, to verify that the fee to be charged for a given order is as expected, before and after signing it with brokerTool.signOrder. This fee is equal or lower than the white-label partner induced fee, provided the order is properly signed.

Kind: instance method of BrokerTool Returns: number -

Fee in decimals (i.e. 0.1% is 0.001).

Param	Type	Description
order	Order	Order structure. As a minimum the structure needs to specify symbol, side, type and quantity.
traderAddr	string	Address of the trader for whom to determine the fee.

Example

import { BrokerTool, PerpetualDataHandler, Order } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(BrokerTool);
  // setup (authentication required, PK is an environment variable with a private key)
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  const pk: string = <string>process.env.PK;
  let brokTool = new BrokerTool(config, pk);
  await brokTool.createProxyInstance();
  // get exchange fee based on an order and trader
  let order: Order = {
      symbol: "MATIC-USD-MATIC",
      side: "BUY",
      type: "MARKET",
      quantity: 100,
      executionTimestamp: Date.now()/1000
  };
   let exchFee = await brokTool.determineExchangeFee(order,
       "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B");
  console.log(exchFee);
}
main();

brokerTool.getCurrentBrokerVolume(poolSymbolName) ⇒ number

Exponentially weighted EMA of the total trading volume of all trades performed under this white-label partner. The weights are chosen so that in average this coincides with the 30 day volume.

Kind: instance method of BrokerTool Returns: number -

Current trading volume for this white-label partner, in USD.

Param	Type	Description
poolSymbolName	string	Pool symbol name (e.g. MATIC, USDC, etc).

Example

import { BrokerTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(BrokerTool);
  // setup (authentication required, PK is an environment variable with a private key)
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  const pk: string = <string>process.env.PK;
  let brokTool = new BrokerTool(config, pk);
  await brokTool.createProxyInstance();
  // get 30 day volume for white-label partner
  let brokVolume = await brokTool.getCurrentBrokerVolume("MATIC");
  console.log(brokVolume);
}
main();

brokerTool.getLotSize(poolSymbolName) ⇒ number

Total amount of collateral currency a white-label partner has to deposit into the default fund to purchase one lot. This is equivalent to the price of a lot expressed in a given pool's currency (e.g. MATIC, USDC, etc).

Kind: instance method of BrokerTool Returns: number -

White-label partner lot size in a given pool's currency, e.g. in MATIC for poolSymbolName MATIC.

Param	Type	Description
poolSymbolName	string	Pool symbol name (e.g. MATIC, USDC, etc).

Example

import { BrokerTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(BrokerTool);
  // setup (authentication required, PK is an environment variable with a private key)
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  const pk: string = <string>process.env.PK;
  let brokTool = new BrokerTool(config, pk);
  await brokTool.createProxyInstance();
  // get lot price
  let brokLotSize = await brokTool.getLotSize("MATIC");
  console.log(brokLotSize);
}
main();

brokerTool.getBrokerDesignation(poolSymbolName) ⇒ number

Provides information on how many lots a white-label partner purchased for a given pool. This is relevant to determine the white-label partner's fee tier.

Kind: instance method of BrokerTool Returns: number -

Number of lots purchased by this white-label partner.

Param	Type	Description
poolSymbolName	string	Pool symbol name (e.g. MATIC, USDC, etc).

Example

import { BrokerTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(BrokerTool);
  // setup (authentication required, PK is an environment variable with a private key)
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  const pk: string = <string>process.env.PK;
  let brokTool = new BrokerTool(config, pk);
  await brokTool.createProxyInstance();
  // get white-label partner designation
  let brokDesignation = await brokTool.getBrokerDesignation("MATIC");
  console.log(brokDesignation);
}
main();

brokerTool.depositBrokerLots(poolSymbolName, lots) ⇒ ContractTransaction

Deposit lots to the default fund of a given pool.

Kind: instance method of BrokerTool Returns: ContractTransaction -

ContractTransaction object.

Param	Type	Description
poolSymbolName	string	Pool symbol name (e.g. MATIC, USDC, etc).
lots	number	Number of lots to deposit into this pool.

Example

import { BrokerTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(BrokerTool);
  // setup (authentication required, PK is an environment variable with a private key)
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  const pk: string = <string>process.env.PK;
  let brokTool = new BrokerTool(config, pk);
  await brokTool.createProxyInstance();
  // deposit to perpetuals
  await brokTool.setAllowance("MATIC");
  let respDeposit = await brokTool.depositBrokerLots("MATIC",1);
  console.log(respDeposit);
}
main();

brokerTool.signOrder(order, traderAddr) ⇒ Order

Adds this white-label partner's signature to a user-friendly order. An order signed by a white-label partner is considered to be routed through this white-label partner and benefits from the white-label partner's fee conditions.

Kind: instance method of BrokerTool Returns: Order -

An order signed by this white-label partner, which can be submitted directly with AccountTrade.order.

Param	Type	Description
order	Order	Order to sign. It must contain valid white-label partner fee, white-label partner address, and order deadline.
traderAddr	string	Address of trader submitting the order.

Example

import { BrokerTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(BrokerTool);
  // setup (authentication required, PK is an environment variable with a private key)
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  const pk: string = <string>process.env.PK;
  let brokTool = new BrokerTool(config, pk);
  await brokTool.createProxyInstance();
  // sign order
  let order = {symbol: "ETH-USD-MATIC",
      side: "BUY",
      type: "MARKET",
      quantity: 1,
      executionTimestamp: Date.now()/1000
   };
   let signedOrder = await brokTool.signOrder(order, "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B",
       0.0001, 1669723339);
  console.log(signedOrder);
  // execute order
  let orderTransaction = await accTrade.order(signedOrder);
  console.log(orderTransaction.hash);
}
main();

brokerTool.signSCOrder(scOrder, traderAddr) ⇒ string

Generates a white-label partner's signature of a smart-contract ready order. An order signed by a white-label partner is considered to be routed through this white-label partner and benefits from the white-label partner's fee conditions.

Kind: instance method of BrokerTool Returns: string -

Signature of order.

Param	Type	Description
scOrder	SmartContractOrder	Order to sign. It must contain valid white-label partner fee, white-label partner address, and order deadline.
traderAddr	string	Address of trader submitting the order.

Example

import { BrokerTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(BrokerTool);
  // setup (authentication required, PK is an environment variable with a private key)
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  const pk: string = <string>process.env.PK;
  const brokTool = new BrokerTool(config, pk);
  const traderAPI = new TraderInterface(config);
  await brokTool.createProxyInstance();
  await traderAPI.createProxyInstance();
  // sign order
  const order = {symbol: "ETH-USD-MATIC",
      side: "BUY",
      type: "MARKET",
      quantity: 1,
      executionTimestamp: Date.now()/1000
   };
  const scOrder = await traderAPI.createSmartContractOrder(order, "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B")
  const signature = await brokTool.signSCOrder(order, "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B",
       0.0001, 1669723339);
  console.log(signature);
}
main();

brokerTool.transferOwnership(poolSymbolName, newAddress) ⇒ ContractTransaction

Transfer ownership of a white-label partner's status to a new wallet. This function transfers the values related to (i) trading volume and (ii) deposited lots to newAddress. The white-label partner needs in addition to manually transfer his D8X holdings to newAddress. Until this transfer is completed, the white-label partner will not have his current designation reflected at newAddress.

Kind: instance method of BrokerTool Returns: ContractTransaction -

ethers transaction object

Param	Type	Description
poolSymbolName	string	Pool symbol name (e.g. MATIC, USDC, etc).
newAddress	string	The address this white-label partner wants to use from now on.

Example

import { BrokerTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(BrokerTool);
  // setup (authentication required, PK is an environment variable with a private key)
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  const pk: string = <string>process.env.PK;
  let brokTool = new BrokerTool(config, pk);
  await brokTool.createProxyInstance();
  // transfer ownership
  let respTransferOwnership = await brokTool.transferOwnership("MATIC", "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B");
  console.log(respTransferOwnership);
}
main();