# Liquidators

### LiquidatorTool ⇐ `WriteAccessHandler`

Functions to liquidate traders. This class requires a private key and executes smart-contract interactions that require gas-payments.

**Kind**: global class\
**Extends**: `WriteAccessHandler`

* [LiquidatorTool](https://d8x.gitbook.io/d8x/node-sdk/modules/broken-reference) ⇐ `WriteAccessHandler`
  * [new LiquidatorTool(config, signer)](https://d8x.gitbook.io/d8x/node-sdk/modules/broken-reference)
  * [.liquidateTrader(symbol, traderAddr, \[liquidatorAddr\], priceFeedData)](https://d8x.gitbook.io/d8x/node-sdk/modules/broken-reference) ⇒
  * [.isMaintenanceMarginSafe(symbol, traderAddr, indexPrices)](https://d8x.gitbook.io/d8x/node-sdk/modules/broken-reference) ⇒ `boolean`
  * [.countActivePerpAccounts(symbol)](https://d8x.gitbook.io/d8x/node-sdk/modules/broken-reference) ⇒ `number`
  * [.getActiveAccountsByChunks(symbol, from, to)](https://d8x.gitbook.io/d8x/node-sdk/modules/broken-reference) ⇒ `Array.<string>`
  * [.getAllActiveAccounts(symbol)](https://d8x.gitbook.io/d8x/node-sdk/modules/broken-reference) ⇒ `Array.<string>`

#### new LiquidatorTool(config, signer)

Constructs a LiquidatorTool instance for a given configuration and private key.

| Param  | Type                 | Description                                                    |
| ------ | -------------------- | -------------------------------------------------------------- |
| config | `NodeSDKConfig`      | Configuration object, see PerpetualDataHandler. readSDKConfig. |
| signer | `string` \| `Signer` | Private key or ethers Signer of the account                    |

**Example**

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

#### liquidatorTool.liquidateTrader(symbol, traderAddr, \[liquidatorAddr], priceFeedData) ⇒

Liquidate a trader.

**Kind**: instance method of [`LiquidatorTool`](https://d8x.gitbook.io/d8x/node-sdk/modules/broken-reference)\
**Returns**:

Transaction object.

| Param             | Type                  | Description                                                                                                                                |
| ----------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| symbol            | `string`              | Symbol of the form ETH-USD-MATIC.                                                                                                          |
| traderAddr        | `string`              | Address of the trader to be liquidated.                                                                                                    |
| \[liquidatorAddr] | `string`              | Address to be credited if the liquidation succeeds.                                                                                        |
| priceFeedData     | `PriceFeedSubmission` | optional. VAA and timestamps for oracle. If not provided will query from REST API. Defaults to the wallet used to execute the liquidation. |

**Example**

```js
import { LiquidatorTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(LiquidatorTool);
  // 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 lqudtrTool = new LiquidatorTool(config, pk);
  await lqudtrTool.createProxyInstance();
  // liquidate trader
  let liqAmount = await lqudtrTool.liquidateTrader("ETH-USD-MATIC",
      "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B");
  console.log(liqAmount);
}
main();
```

#### liquidatorTool.isMaintenanceMarginSafe(symbol, traderAddr, indexPrices) ⇒ `boolean`

Check if the collateral of a trader is above the maintenance margin ("maintenance margin safe"). If not, the position can be liquidated.

**Kind**: instance method of [`LiquidatorTool`](https://d8x.gitbook.io/d8x/node-sdk/modules/broken-reference)\
**Returns**: `boolean` -

True if the trader is maintenance margin safe in the perpetual. False means that the trader's position can be liquidated.

| Param       | Type             | Description                                              |
| ----------- | ---------------- | -------------------------------------------------------- |
| symbol      | `string`         | Symbol of the form ETH-USD-MATIC.                        |
| traderAddr  | `string`         | Address of the trader whose position you want to assess. |
| indexPrices | `Array.<number>` | optional, index price S2/S3 for which we test            |

**Example**

```js
import { LiquidatorTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(LiquidatorTool);
  // 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 lqudtrTool = new LiquidatorTool(config, pk);
  await lqudtrTool.createProxyInstance();
  // check if trader can be liquidated
  let safe = await lqudtrTool.isMaintenanceMarginSafe("ETH-USD-MATIC",
      "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B");
  console.log(safe);
}
main();
```

#### liquidatorTool.countActivePerpAccounts(symbol) ⇒ `number`

Total number of active accounts for this symbol, i.e. accounts with positions that are currently open.

**Kind**: instance method of [`LiquidatorTool`](https://d8x.gitbook.io/d8x/node-sdk/modules/broken-reference)\
**Returns**: `number` -

Number of active accounts.

| Param  | Type     | Description                       |
| ------ | -------- | --------------------------------- |
| symbol | `string` | Symbol of the form ETH-USD-MATIC. |

**Example**

```js
import { LiquidatorTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(LiquidatorTool);
  // 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 lqudtrTool = new LiquidatorTool(config, pk);
  await lqudtrTool.createProxyInstance();
  // get number of active accounts
  let accounts = await lqudtrTool.countActivePerpAccounts("ETH-USD-MATIC");
  console.log(accounts);
}
main();
```

#### liquidatorTool.getActiveAccountsByChunks(symbol, from, to) ⇒ `Array.<string>`

Get addresses of active accounts by chunks.

**Kind**: instance method of [`LiquidatorTool`](https://d8x.gitbook.io/d8x/node-sdk/modules/broken-reference)\
**Returns**: `Array.<string>` -

Array of addresses at locations 'from', 'from'+1 ,..., 'to'-1.

| Param  | Type     | Description                                       |
| ------ | -------- | ------------------------------------------------- |
| symbol | `string` | Symbol of the form ETH-USD-MATIC.                 |
| from   | `number` | From which account we start counting (0-indexed). |
| to     | `number` | Until which account we count, non inclusive.      |

**Example**

```js
import { LiquidatorTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(LiquidatorTool);
  // 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 lqudtrTool = new LiquidatorTool(config, pk);
  await lqudtrTool.createProxyInstance();
  // get all active accounts in chunks
  let accounts = await lqudtrTool.getActiveAccountsByChunks("ETH-USD-MATIC", 0, 4);
  console.log(accounts);
}
main();
```

#### liquidatorTool.getAllActiveAccounts(symbol) ⇒ `Array.<string>`

Addresses for all the active accounts in this perpetual symbol.

**Kind**: instance method of [`LiquidatorTool`](https://d8x.gitbook.io/d8x/node-sdk/modules/broken-reference)\
**Returns**: `Array.<string>` -

Array of addresses.

| Param  | Type     | Description                       |
| ------ | -------- | --------------------------------- |
| symbol | `string` | Symbol of the form ETH-USD-MATIC. |

**Example**

```js
import { LiquidatorTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(LiquidatorTool);
  // 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 lqudtrTool = new LiquidatorTool(config, pk);
  await lqudtrTool.createProxyInstance();
  // get all active accounts
  let accounts = await lqudtrTool.getAllActiveAccounts("ETH-USD-MATIC");
  console.log(accounts);
}
main();
```