# 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](broken://pages/p0JT9fO3wZS51DfYaqsj) ⇐ `WriteAccessHandler`
  * [new LiquidatorTool(config, signer)](broken://pages/p0JT9fO3wZS51DfYaqsj)
  * [.liquidateTrader(symbol, traderAddr, \[liquidatorAddr\], priceFeedData)](broken://pages/p0JT9fO3wZS51DfYaqsj) ⇒
  * [.isMaintenanceMarginSafe(symbol, traderAddr, indexPrices)](broken://pages/p0JT9fO3wZS51DfYaqsj) ⇒ `boolean`
  * [.countActivePerpAccounts(symbol)](broken://pages/p0JT9fO3wZS51DfYaqsj) ⇒ `number`
  * [.getActiveAccountsByChunks(symbol, from, to)](broken://pages/p0JT9fO3wZS51DfYaqsj) ⇒ `Array.<string>`
  * [.getAllActiveAccounts(symbol)](broken://pages/p0JT9fO3wZS51DfYaqsj) ⇒ `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`](broken://pages/p0JT9fO3wZS51DfYaqsj)\
**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`](broken://pages/p0JT9fO3wZS51DfYaqsj)\
**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`](broken://pages/p0JT9fO3wZS51DfYaqsj)\
**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`](broken://pages/p0JT9fO3wZS51DfYaqsj)\
**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`](broken://pages/p0JT9fO3wZS51DfYaqsj)\
**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();
```


---

# 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/liquidators.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.