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 and requires an API Key, which you can get by signing up for a Free account on the OpenPool Developer Portal.

The OpenPool SDK currently supports the following chains:

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

🌟 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
• 🏁 Getting Started
  • Requirements
  • Installation
• 🛠️ Usage
  • Initialize SDK
  • Making requests
  • Examples
• 📖 API Reference

🏁 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 (it’s Free to sign up).

Installation

npm install @openpool/openpool-sdk

🛠️ Usage

Initialization

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

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

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

const openpool = new OpenPool(config);

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

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

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

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

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

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

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

Table of Contents

1. Label SDK Methods
2. Balances SDK Methods
3. Metadata SDK Methods
4. Accounting SDK Methods
5. Wallet Registrations SDK Methods
6. Transactions SDK Methods
7. Transfers SDK Methods
8. Total P&L SDK Methods
9. Definitive Specific Methods

Label SDK 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

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

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

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

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

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

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

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

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

 {
  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

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