> For the complete documentation index, see [llms.txt](https://docs.orbs.network/orbs-integrations/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.orbs.network/orbs-integrations/twap-sdk/usage.md).

# Usage

### **Creating SDK Instance**

To start using the SDK in your dApp, you first need to create an instance of it. This instance provides the primary functionality to interact with the Orbs dTWAP protocol.

```javascript
import { constructSDK } from "@orbs-network/twap-sdk";

const twapSDK = constructSDK({
  config
});
```

*Note:* To obtain a config object, you must contact Orbs and setup your desired parameters, along with deploying the appropriate contracts.

**Example of a dTWAP config object:**

```
{
   "chainName": "eth",
   "chainId": 1,
   "twapVersion": 4,
   "twapAddress": "0x0000000000000000000000000000000000000000",
   "lensAddress": "0x0000000000000000000000000000000000000000",
   "bidDelaySeconds": 60,
   "minChunkSizeUsd": 100,
   "name": "DexSwap",
   "partner": "Orbs:TWAP:DexSwap",
   "exchangeAddress": "0x0000000000000000000000000000000000000000",
   "exchangeType": "ParaswapExchange",
   "pathfinderKey": ""
}
```

### Derived Swap Values

The `derivedSwapValues` function takes the inputs from the UI and derives all the values required for the TWAP order.

```javascript
const derivedSwapValues = twapSDK.derivedSwapValues({
  srcAmount,          // user input src amount in bigint format
  price,              // optional: user input limit price 
  customChunks,       // optional: user input number of chunks
  customDuration,     // optional: user input duration
  customFillDelay,    // optional: user input fill delay
  isLimitPanel,       // boolean for whether user select limit panel
  oneSrcTokenUsd,     // USD value of 1 src token
  srcDecimals,        // number of decimals of src token
  destDecimals,       // number of decimals for dest token
  isMarketOrder,      // boolean for whether user selected market order
});
```

The following arguments `customChunks`, `customDuration` and `customFillDelay` all have default values, so only pass these in if the user specifies them in the UI.

### Prepare Order Arguments

The `prepareOrderArgs` function takes the values from `derivedSwapValues` and parses them into arguments for the dTWAP contract method.

```javascript
const askParams = twapSDK.prepareOrderArgs({
  destTokenMinAmount: derivedSwapValues.destTokenMinAmount,
  srcChunkAmount: derivedSwapValues.srcChunkAmount,
  deadline: derivedSwapValues.deadline,
  fillDelay: derivedSwapValues.fillDelay,
  srcAmount,            // user input src amount in bigint format
  srcTokenAddress,      // src token address
  destTokenAddress,     // dest token address
});
```

### Order Deadline

You can use orderDeadline to get the deadline of an order to display to the user. This needs to be updated at an interval with the current time.

```javascript
const deadline = twapSDK.orderDeadline(
  currentTime,    // The current time as number e.g. Date.now()
  duration        // The duration from derivedSwapValues
)
```

### Get Orders

Returns a list of all a user's orders.

```javascript
const orders = await twapSDK.getOrders(
  account,        // The user account
  signal          // optional: abort signal
)
```

### Wait For Orders Update

Retries fetching the user’s orders until the specific order is found. This function is useful after creating a new order, when you want to wait for confirmation that the new order has been successfully created.

```javascript
const updatedOrders = await twapSDK.waitForOrdersUpdate(
  orderId,        // The order Id to find
  account         // The user account
);
```

### Best Practices

#### Limit Deadline

When the user selects the limit panel we suggest to set the default deadline of the order to 1 week and if TWAP, set it to undefined as it will be derived from the chunks and fill delay.

#### Warnings

```javascript
partialFill
minFillDelay
maxFillDelay
minDuration
maxDuration
tradeSize
```

The `derivedSwapValues` SDK function returns a warnings object containing the boolean properties above.

We recommend displaying a message to the user in the UI for each of these warnings if they are true.