> For the complete documentation index, see [llms.txt](https://d8x.gitbook.io/d8x/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://d8x.gitbook.io/d8x/node-sdk/modules/white-label-partners.md).

# 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](broken://pages/q1lVDAjjhnafQmOG7etZ) ⇐ `WriteAccessHandler`
  * [new BrokerTool(config, privateKey, signer)](broken://pages/q1lVDAjjhnafQmOG7etZ)
  * [.getBrokerInducedFee(poolSymbolName)](broken://pages/q1lVDAjjhnafQmOG7etZ) ⇒ `number`
  * [.getFeeForBrokerDesignation(poolSymbolName, \[lots\])](broken://pages/q1lVDAjjhnafQmOG7etZ) ⇒ `number`
  * [.getFeeForBrokerVolume(poolSymbolName)](broken://pages/q1lVDAjjhnafQmOG7etZ) ⇒ `number`
  * [.getFeeForBrokerStake(\[brokerAddr\])](broken://pages/q1lVDAjjhnafQmOG7etZ) ⇒ `number`
  * [.determineExchangeFee(order, traderAddr)](broken://pages/q1lVDAjjhnafQmOG7etZ) ⇒ `number`
  * [.getCurrentBrokerVolume(poolSymbolName)](broken://pages/q1lVDAjjhnafQmOG7etZ) ⇒ `number`
  * [.getLotSize(poolSymbolName)](broken://pages/q1lVDAjjhnafQmOG7etZ) ⇒ `number`
  * [.getBrokerDesignation(poolSymbolName)](broken://pages/q1lVDAjjhnafQmOG7etZ) ⇒ `number`
  * [.depositBrokerLots(poolSymbolName, lots)](broken://pages/q1lVDAjjhnafQmOG7etZ) ⇒ `ContractTransaction`
  * [.signOrder(order, traderAddr)](broken://pages/q1lVDAjjhnafQmOG7etZ) ⇒ `Order`
  * [.signSCOrder(scOrder, traderAddr)](broken://pages/q1lVDAjjhnafQmOG7etZ) ⇒ `string`
  * [.transferOwnership(poolSymbolName, newAddress)](broken://pages/q1lVDAjjhnafQmOG7etZ) ⇒ `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**

```js
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`](broken://pages/q1lVDAjjhnafQmOG7etZ)\
**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**

```js
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`](broken://pages/q1lVDAjjhnafQmOG7etZ)\
**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**

```js
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`](broken://pages/q1lVDAjjhnafQmOG7etZ)\
**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**

```js
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`](broken://pages/q1lVDAjjhnafQmOG7etZ)\
**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**

```js
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`](broken://pages/q1lVDAjjhnafQmOG7etZ)\
**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**

```js
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`](broken://pages/q1lVDAjjhnafQmOG7etZ)\
**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**

```js
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`](broken://pages/q1lVDAjjhnafQmOG7etZ)\
**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**

```js
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`](broken://pages/q1lVDAjjhnafQmOG7etZ)\
**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**

```js
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`](broken://pages/q1lVDAjjhnafQmOG7etZ)\
**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**

```js
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`](broken://pages/q1lVDAjjhnafQmOG7etZ)\
**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**

```js
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`](broken://pages/q1lVDAjjhnafQmOG7etZ)\
**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**

```js
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`](broken://pages/q1lVDAjjhnafQmOG7etZ)\
**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**

```js
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();
```