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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://d8x.gitbook.io/d8x/node-sdk/modules/white-label-partners.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.