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


---

# 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://docs.orbs.network/orbs-integrations/twap-sdk/usage.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.