npm package: @openpool/openpool-definitive-sdk
Description: The OpenPool Reporting SDK is a Typescript SDK for retrieving detailed onchain reporting data. This package is tailored for Definitive with custom SDK methods to meet their vault specifications
Author: Joe Toledano joe@openpool.co
Latest version: 0.0.4

# 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/openpool-sdk
```

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

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

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

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

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/openpool-definitive-sdk";

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/openpool-definitive-sdk";

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/openpool-definitive-sdk";

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/openpool-definitive-sdk";

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/openpool-definitive-sdk";

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. [Label SDK Methods](#label-api-methods)
2. [Balances SDK Methods](#balances-api-methods)
3. [Metadata SDK Methods](#metadata-api-methods)
4. [Accounting SDK Methods](#accounting-api-methods)
5. [Wallet Registrations SDK Methods](#wallet-registrations-api-methods)
6. [Transactions SDK Methods](#transactions-api-methods)
7. [Transfers SDK Methods](#transfers-api-methods)
8. [Total P&L SDK Methods](#total-p&L-methods)
9. [Definitive Specific Methods](#definitive-methods)

---

## [Label SDK Methods](#label-api-methods)

### `getAllLabels(query?: { page?: number })`

#### Description

Get a list of all of your custom labels.

- **OpenPool API Endpoint:** `GET:/label/custom/`

#### Parameters

| Name  | Type   | Description      | Optional |
| ----- | ------ | ---------------- | -------- |
| query | object | Pagination query | Yes      |

---

### `createLabel(data: AddressLabel)`

#### Description

Create a custom label for a specific 0x address.

- **OpenPool API Endpoint:** `POST:/label/custom/`

#### Parameters

| Name | Type         | Description       | Optional |
| ---- | ------------ | ----------------- | -------- |
| data | AddressLabel | Label information | No       |

---

### `getLabel(labelId: string)`

#### Description

Get a specific custom label by its ID.

- **OpenPool API Endpoint:** `GET:/label/custom/`

#### Parameters

| Name    | Type   | Description     | Optional |
| ------- | ------ | --------------- | -------- |
| labelId | string | ID of the label | No       |

---

### `updateLabel(labelId: string, data: AddressLabel)`

#### Description

Update a custom label.

- **OpenPool API Endpoint:** `PUT:/label/custom/{id}/`

#### Parameters

| Name    | Type         | Description           | Optional |
| ------- | ------------ | --------------------- | -------- |
| labelId | string       | ID of the label       | No       |
| data    | AddressLabel | New label information | No       |

---

### `partialUpdateLabel(labelId: string, data: PatchedAddressLabel)`

#### Description

Partially update a custom label.

- **OpenPool API Endpoint:** `PATCH:/label/custom/{id}/`

#### Parameters

| Name    | Type                | Description      | Optional |
| ------- | ------------------- | ---------------- | -------- |
| labelId | string              | ID of the label  | No       |
| data    | PatchedAddressLabel | Fields to update | No       |

---

### `deleteLabel(labelId: string)`

#### Description

Delete a custom label.

- **OpenPool API Endpoint:** `DELETE:/label/custom/{id}/`

#### Parameters

| Name    | Type   | Description     | Optional |
| ------- | ------ | --------------- | -------- |
| labelId | string | ID of the label | No       |

---

## [Balances SDK Methods](#balances-api-methods)

### `getTokenBalances(params: WalletBalanceQuery)`

#### Description

Get token balances and performance.

- **OpenPool API Endpoint:** `GET:/wallet/balance/`

#### Parameters

| Name   | Type               | Description      | Optional |
| ------ | ------------------ | ---------------- | -------- |
| params | WalletBalanceQuery | Query parameters | No       |

---

### `getDeFiBalances(params: WalletDeFiBalanceQuery)`

#### Description

Get DeFi balances and performance.

- **OpenPool API Endpoint:** `GET:/wallet/defi_balance/`

#### Parameters

| Name   | Type                   | Description      | Optional |
| ------ | ---------------------- | ---------------- | -------- |
| params | WalletDeFiBalanceQuery | Query parameters | No       |

---

### `getNFTBalances(params: WalletNftBalanceQuery)`

#### Description

Get NFT balances and performance.

- **OpenPool API Endpoint:** `GET:/wallet/nft_balance/`

#### Parameters

| Name   | Type                  | Description      | Optional |
| ------ | --------------------- | ---------------- | -------- |
| params | WalletNftBalanceQuery | Query parameters | No       |

---

### `getPortfolioSummary(params: WalletPortfolioQuery)`

#### Description

Get overall summary of balances and performance for tokens and DeFi positions.

- **OpenPool API Endpoint:** `GET:/wallet/portfolio_summary/`

#### Parameters

| Name   | Type                 | Description      | Optional |
| ------ | -------------------- | ---------------- | -------- |
| params | WalletPortfolioQuery | Query parameters | No       |

---

### `getPortfolioBalances(params: WalletPortfolioQuery)`

#### Description

Get overall list of portfolio balances and performance for tokens and DeFi positions.

- **OpenPool API Endpoint:** `GET:/wallet/portfolio/`

#### Parameters

| Name   | Type                 | Description      | Optional |
| ------ | -------------------- | ---------------- | -------- |
| params | WalletPortfolioQuery | Query parameters | No       |

---

## [Metadata SDK Methods](#metadata-api-methods)

### `getAssets(params?: AssetQuery)`

#### Description

Retrieve metadata about assets.

- **OpenPool API Endpoint:** `GET:/metadata/asset/`

#### Parameters

| Name   | Type       | Description      | Optional |
| ------ | ---------- | ---------------- | -------- |
| params | AssetQuery | Query parameters | Yes      |

---

### `getBlockchains(params?: BlockchainQuery)`

#### Description

Retrieve metadata about blockchains.

- **OpenPool API Endpoint:** `GET:/metadata/blockchain/`

#### Parameters

| Name   | Type            | Description      | Optional |
| ------ | --------------- | ---------------- | -------- |
| params | BlockchainQuery | Query parameters | Yes      |

---

### `getSmartContracts(params?: ContractQuery)`

#### Description

Query database of 20K+ smart contracts to get tags and labels.

- **OpenPool API Endpoint:** `GET:/metadata/contract/`

#### Parameters

| Name   | Type          | Description      | Optional |
| ------ | ------------- | ---------------- | -------- |
| params | ContractQuery | Query parameters | Yes      |

---

### `getProtocols(params?: ProtocolQuery)`

#### Description

Retrieve metadata about protocols.

- **OpenPool API Endpoint:** `GET:/metadata/protocol/`

#### Parameters

| Name   | Type          | Description      | Optional |
| ------ | ------------- | ---------------- | -------- |
| params | ProtocolQuery | Query parameters | Yes      |

---

### `getTokens(params?: TokenQuery)`

#### Description

Retrieve metadata about tokens.

- **OpenPool API Endpoint:** `GET:/metadata/token/`

#### Parameters

| Name   | Type       | Description      | Optional |
| ------ | ---------- | ---------------- | -------- |
| params | TokenQuery | Query parameters | Yes      |

---

## [Accounting SDK Methods](#accounting-api-methods)

### `getAccountingHistory(params: WalletAccountingHistoryQuery)`

#### Description

Fetches wallet accounting history based on the given query and request parameters.

- **OpenPool API Endpoint:** `GET:/wallet/accounting_history/`

#### Parameters

| Name   | Type                         | Description                      | Optional |
| ------ | ---------------------------- | -------------------------------- | -------- |
| params | WalletAccountingHistoryQuery | Query parameters for the request | No       |

---

## [Wallet Registrations SDK Methods](#wallet-registrations-api-methods)

### `getWalletRegistrations(params?: WalletManageListQuery)`

#### Description

Query this endpoint to get a list of all the wallet addresses you have registered with OpenPool.

- **OpenPool API Endpoint:** `GET:/wallet/manage/`

#### Parameters

| Name   | Type                  | Description                      | Optional |
| ------ | --------------------- | -------------------------------- | -------- |
| params | WalletManageListQuery | Query parameters for the request | Yes      |

---

### `registerWallet(data: Address)`

#### Description

Register a new address with OpenPool.

- **OpenPool API Endpoint:** `POST:/wallet/manage/`

#### Parameters

| Name | Type    | Description                  | Optional |
| ---- | ------- | ---------------------------- | -------- |
| data | Address | The address to be registered | No       |

---

## [Transactions SDK Methods](#transactions-api-methods)

### `getTransactions(query: WalletTransactionListQuery)`

#### Description

Use this method to get a list of all the transactions for the wallets you have registered with OpenPool.

- **OpenPool API Endpoint:** `GET:/wallet/transaction/`

#### Parameters

| Name  | Type                       | Description                      | Optional |
| ----- | -------------------------- | -------------------------------- | -------- |
| query | WalletTransactionListQuery | Query parameters for the request | No       |

---

## [Transfers SDK Methods](#transfers-api-methods)

### `getTransfers(query: WalletTransferListQuery)`

#### Description

Get a list of all transfers (cashflows) related to the registered wallets.

- **OpenPool API Endpoint:** `GET:/wallet/transfer/`

#### Parameters

| Name  | Type                    | Description                      | Optional |
| ----- | ----------------------- | -------------------------------- | -------- |
| query | WalletTransferListQuery | Query parameters for the request | No       |

---

## [Total P&L SDK Methods](#total-p&l-methods)

### `getTotalUnrealizedPnl(query: WalletBalanceQuery)`

#### Description

Get the overall unrealized tokens PnL for an address, in the currency specified.

- **OpenPool API Endpoint:** `GET:/wallet/balance/`

#### Parameters

| Name  | Type               | Description                      | Optional |
| ----- | ------------------ | -------------------------------- | -------- |
| query | WalletBalanceQuery | Query parameters for the request | No       |

---

### `getTotalRealizedPnl(query: WalletBalanceQuery)`

#### Description

Get the overall realized tokens PnL for an address, in the currency specified and using your chosen accounting method.

- **OpenPool API Endpoint:** `GET:/wallet/balance/`

#### Parameters

| Name  | Type               | Description                      | Optional |
| ----- | ------------------ | -------------------------------- | -------- |
| query | WalletBalanceQuery | Query parameters for the request | No       |

---

---

## [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"
}
```

---