npm package: @openpool/definitive
Description: The OpenPool Reporting SDK is a Typescript SDK for retrieving detailed onchain reporting data.
Author: Joe Toledano joe@openpool.co
Latest version: 1.0.1

# OpenPool Onchain Reporting SDK

The OpenPool Reporting SDK is a Typescript SDK for retrieving detailed onchain reporting data.

Processing and navigating blockchain transaction data is time-consuming, while creating accurate on-chain reporting demands precision and financial know-how. OpenPool's SDK allows you to build bespoke financial dashboards and internal reporting to support business operations and customer demands.
The OpenPool SDK is powered by the [OpenPool API](https://docs.openpool.co/reference/getting-started-with-openpool-api) and requires an API Key, which you can get by signing up for a Free account on the [OpenPool Developer Portal](https://dev.openpool.co).

The OpenPool SDK currently supports the following chains:

- Ethereum
- Polygon
- Base
- Optimism
- Arbitrum
- Gnosis
- Avalanche
- BNB

## [🌟 Features](#-features)

- 📈 **Detailed Wallet Balances & Performance**: Retrieve the real-time and historical enriched balances and performance (with unrealized + realized P&L) data of a given wallet or contract’s tokens (ERC-20’s), NFTs, and DeFi staked positions.
- 📒 **Flexible Wallet Accounting History:** Query an enriched human-readable transaction history with accounting data for a given wallet or contract. For these requests, a custom cost-method and base-currency can be provided.
- 🏷️ **Customizable Address Labels**: Create, update and manage custom smart contract names for counterparty addresses your wallet interacts with.
- 📇 **Detailed Metadata**: Retrieve metadata for Smart Contracts, Assets, Blockchains, Protocols and Tokens.
- 🔒 **Typescript**: Written in Typescript with full type-safety
- ➕ ...and more!

## 📚 Table of Contents

- [🌟 Features](#-features)
- [🏁 Getting Started](#-getting-started)
  - [Requirements](#requirements)
  - [Installation](#installation)
- [🛠️ Usage](#️-usage)
  - [Initialize SDK](#initialize-sdk)
  - [Making requests](#making-requests)
  - [Examples](#examples)
- [📖 API Reference](#-api-reference)
  <!-- - [🔒 License](#-license) -->
    <!-- - [❗ Error Handling](#-error-handling) -->
    <!-- - [🤝 Contributing](#-contributing) -->

## [🏁 Getting Started](#-getting-started)

In order to make requests with the OpenPool SDK you will need to first sign up for an API Key on the [OpenPool Dev Portal](https://dev.openpool.co) (it’s Free to sign up).

### [Installation](#installation)

```bash
npm install @openpool/definitive
```

### [🛠️ Usage](#-usage)

**[Initialization](#-initialize-sdk)**

Once you install the SDK, you can initialize it like so:

```bash
import { OpenPool } from "@openpool/definitive";

const config = {
  apiKey: 'whatILearnedInBoatingSchoolIs', // Replace with your OpenPool API key.
};

const openpool = new OpenPool(config);
```

**[Making requests](#making-requests)**

Every address that you will want to retrieve data for will need to be registered first. Once registered, an address will have an `is_loaded` field that will update upon the completion of its transactions being processed.

**💡 How to register an address**

```bash
import { OpenPool } from "@openpool/definitive";

const config = {
  apiKey: 'whatILearnedInBoatingSchoolIs', // Replace with your OpenPool API key.
};

const openpool = new OpenPool(config);

const registerAddress = async (address: string) => {
  try {
    const requestBody = {address}
    const response = await openpool.registerWallet(requestBody);
    return response
  }
  catch(e){
    // Handle Error
  }
  finally {
    // Do something...
  }
}

const registerWalletResponse = await registerAddress('0x123abc')
```

**💡 How to look up the registration status of an address**

```bash
import { OpenPool } from "@openpool/definitive";

const config = {
  apiKey: 'whatILearnedInBoatingSchoolIs', // Replace with your OpenPool API key.
};

const openpool = new OpenPool(config);

const lookupTheRegistrationStatusOfAnAddress = async (address: string) => {
  try {
    const requestBody = {address}
    const response = await openpool.getWalletRegistrations(requestBody);
    const registrationStatusResults = response.results
    const registrationStatus = response.results[0].is_loaded
    return registrationStatus
  }
  catch(e){
    // Handle Error
  }
  finally {
    // Do something...
  }
}

const walletRegistrationStatus = await lookupTheRegistrationStatusOfAnAddress('0x123abc')
```

**[Examples](#examples)**

Fetching the **token balance and performance in USD** of a given address

```bash
import { OpenPool } from "@openpool/definitive";

const config = {
  apiKey: 'whatILearnedInBoatingSchoolIs', // Replace with your OpenPool API key.
};

const openpool = new OpenPool(config);

const getTokenBalancesForAnAddress = async (address: string) => {
  try {
    const params = { wallet: address }
    const tokenBalanceResponse = await openpool.getTokenBalances(params);
    return tokenBalanceResponse.result;
  }
  catch(e){
    // Handle Error
  }
  finally {
    // Do something...
  }
}

```

Fetching the **enriched transactions data** for a set of addresses

```bash
import { OpenPool } from "@openpool/definitive";

const config = {
  apiKey: 'whatILearnedInBoatingSchoolIs', // Replace with your OpenPool API key.
};

const openpool = new OpenPool(config);

const getTransactionsForAddress = async (address: string) => {
  try {
    const params = { wallet: address }
    const transactionsResponse = await openpool.getTransactions(params);
    return transactionsResponse.result;
  }
  catch(e) {
    // Handle Error
  }
  finally {
    // Do something...
  }
}

const transactions = await getTransactionsForAddress("0x123abc, 0x456cdef, 0x789ghi")

```

Getting the **total unrealized P&L** of a given address

```bash
import { OpenPool } from "@openpool/definitive";

const config = {
  apiKey: 'whatILearnedInBoatingSchoolIs', // Replace with your OpenPool API key.
};

const openpool = new OpenPool(config);
    const params = { wallet: address }

const getTotalUnrealizedPnl = async (address: string) => {
  try {
    const params = { wallet: address }
    const transactionsResponse = await openpool.getTotalUnrealizedPnl(params);
    return transactionsResponse.value;
  }
  catch(e) {
    // Handle Error
  }
  finally {
    // Do something...
  }
}

const unrealizedPnl = await getTotalUnrealizedPnl('0x123abc')

```

# [📖 API Reference](#-api-reference)

## Table of Contents

1. [Core SDK Methods](#label-api-methods)
2. [Definitive Specific Methods](#definitive-methods)

---

## [Core SDK Methods](#core-sdk-methods)

The core methods for the SDK can be found in its Readme on its NPM page [here](https://www.npmjs.com/package/@openpool/openpool-sdk#api-reference).

## [Definitive Specific Methods](#definitive-methods)

### `getDefinitiveNAV(query: PrivateDefinitiveNAVQuery)`

#### Description

Get the NAV of a given Definitive vault address, in the time period specified.

- **OpenPool API Endpoint:** `GET:/private/definitive/nav/`

#### Parameters

| Name  | Type                      | Description                                                                                               | Optional |
| ----- | ------------------------- | --------------------------------------------------------------------------------------------------------- | -------- |
| query | PrivateDefinitiveNAVQuery | Requires a token_address, vault_address, and optionally a period ("Y", "3M", "D", "M", "MAX", "W", "YTD") | No       |

#### PrivateDefinitiveNAVQuery Interface

```bash
 {
  token_address: string;
  vault_address: string;
  period?: "Y" | "3M" | "D" | "M" | "MAX" | "W" | "YTD"
}
```

---

### `getDefinitiveUserPerformance(query: PrivateDefinitiveUserPerformanceQuery)`

#### Description

Get the performance of a specific Definitive user's address, in the specified time period

- **OpenPool API Endpoint:** `GET:/private/definitive/performance/`

#### Parameters

| Name  | Type                                  | Description                                                                                                                   | Optional |
| ----- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------- |
| query | PrivateDefinitiveUserPerformanceQuery | Requires a token_address, vault_address, user_address, type, and optionally a period ("Y", "3M", "D", "M", "MAX", "W", "YTD") | No       |

#### PrivateDefinitiveUserPerformanceQuery Interface

```bash
 {
  token_address: string;
  user_address: string;
  vault_address: string;
  type?: "twr" | "notional"
  period?: "Y" | "3M" | "D" | "M" | "MAX" | "W" | "YTD"
}
```

---