Integration

This guide provides step-by-step instructions for developers to easily integrate with the Definitive API.

Step 1: Install the Definitive TypeScript NPM Module

First, you need to install the Definitive TypeScript NPM module. Run the following command in your project directory:

npm i definitive-ts

This command installs the necessary package to interact with the Definitive API in your project.

Step 2: Initialize SDK and Fetch Vaults

Import the DefinitiveApi from the installed package and initialize it with your API key. Use the following code to fetch all community vaults:

import { DefinitiveApi } from "definitive-ts";

const api = new DefinitiveApi({
  HEADERS: { "api-key": "YOUR_API_KEY" },
});

api.default
  .getVaults()
  .then((res) => console.log(res))
  .catch((e) => console.error(e));
// Some code

Replace "YOUR_API_KEY" with your actual API key. This will return a list of all supported vaults.

Step 3: Request a Deposit Payload for an Address

To deposit into a vault, you need to request a deposit payload. Use the vault ID and address to request this payload. Here's an example:

const vaultId = "YOUR_VAULT_ID";
const address = "YOUR_ADDRESS";
const resp = await api.default.postVaultsDeposit(vaultId, address, {
  depositAmounts: { "TOKEN_ADDRESS": "AMOUNT" },
  slippage: "SLIPPAGE_PERCENTAGE",
});

const { data, to, value } = resp.payload;

Replace YOUR_VAULT_ID, YOUR_ADDRESS, TOKEN_ADDRESS, and SLIPPAGE_PERCENTAGE with the appropriate values.

Step 4: Send Transaction

You can send the transaction using wagmi or web3.js.

Using wagmi

If you are using wagmi, use the following code.

import { prepareSendTransaction, sendTransaction } from '@wagmi/core'

const chainId = YOUR_CHAIN_ID;
const config = prepareSendTransaction({
    chainId,
    request: { data, to, value },
});
const result = await sendTransaction(config);

Using web3.js

For web3.js, the code will be as follows:

const privateKey = "YOUR_PRIVATE_KEY";

const createTransaction = await web3.eth.accounts.signTransaction(
	{
	    data,
	    to,
	    value,
	    gas: 21000,
	    gasPrice: await web3.eth.getGasPrice(),
	    nonce: await web3.eth.getTransactionCount(address),
	},
	privateKey
);

const createReceipt = await web3.eth.sendSignedTransaction(
	createTransaction.rawTransaction
);

console.log(`Transaction successful with hash: ${createReceipt.transactionHash}`);

Step 5: Get Position After Depositing

To get information on the position after depositing

const positionResp = await api.default.getVaultsPosition(vaultId, address);
console.log(positionResp);

This will return position information with all necessary data to display on the UI.

{
    "nav": "1199.19",
    "navBasis": {
        "amount": "1505.9004906537218441643815459453886",
        "ticker": "MATIC"
    },
    "balances": [
        {
            "ticker": "DEF",
            "address": "0x8347B60460421EE565F3aC26DaFbAC9D2fE8930e",
            "chainId": "137",
            "amount": "1474.569712951636723258"
        }
    ],
    "totalReturn": {
        "id": "e7f7e26a-904a-45a5-a0ce-6de0d4be93ec",
        "ticker": "MATIC",
        "address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
        "decimals": 18,
        "chainId": "137",
        "image": "https://definitive-icons.s3.amazonaws.com/assets/matic",
        "amount": "36.7481898737218441643815459453886",
        "notional": "29.2636"
    },
    "deposits": [
        {
            "id": "2b2a5e22-a931-44de-94d8-ca945d548966",
            "ticker": "WMATIC",
            "address": "0x0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270",
            "decimals": 18,
            "chainId": "137",
            "image": "https://definitive-icons.s3.amazonaws.com/assets/wmatic",
            "amount": "1469.15230078",
            "notional": "1277.73",
            "baseCurrency": {
                "amount": "1469.15230078",
                "ticker": "MATIC"
            }
        }
    ],
    "llsd": {
        "ltv": "0.8663219802915238388",
        "debt": [
            {
                "id": "2b2a5e22-a931-44de-94d8-ca945d548966",
                "ticker": "WMATIC",
                "address": "0x0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270",
                "decimals": 18,
                "chainId": "137",
                "image": "https://definitive-icons.s3.amazonaws.com/assets/wmatic",
                "amount": "9719.9798784776379713751623668449128388",
                "notional": "7740.281084936359603166604655363078800070053090486528"
            }
        ],
        "collateral": [
            {
                "id": "e58d95a8-4803-4936-926b-c2729a0036a4",
                "ticker": "stMATIC",
                "address": "0x3A58a54C066FdC0f2D55FC9C89F0415C92eBf3C4",
                "decimals": 18,
                "chainId": "137",
                "image": "https://definitive-icons.s3.amazonaws.com/assets/stmatic",
                "amount": "10158.8889306889347097242110764955270136",
                "notional": "8939.470098631003813686644567892738809371887422478048"
            }
        ],
        "unclaimedRewards": []
    },
    "shareConversions": {
        "WMATIC": "1.0171383921763671",
        "stMATIC": "1.12396877160847293019083183874410732"
    }
}