How to get enriched transactions

Whether you’re a building a wallet, investing from smart contracts, or building out tax-solutions, accessing high-quality financial-accounting data is critical to ensuring you’re accurately capturing both yours and your users activity and performance.
With OpenPool’s API’s you can seamlessly access comprehensive contract & wallet accounting and reporting data for all your applications

This article will walkthrough how you can pull in detailed, accounting-data enriched transactions for a given EVM address(es). With these requests, you will be able to see extremely detailed financial-accounting breakdowns and summaries that include fields such as cost-basis with customizable cost-methods, cash-flows, realized P&L to help power what you’re building.

Before we get started

You will need an API key to start making requests, so let’s first generate one from the OpenPool Dev Portal:

Visit the Dev Portal at https://dev.openpool.co/
Sign up or login to your account

Untitled

Create a Project and give it a name

Untitled

Awesome! Now that we have this covered, we’ll need to register the 0x address before you can start making any API calls. We covered this in a separate article and you can find [here] or in the docs.

Retrieving Accounting-Enriched Transactions

This request is a straightforward paginated GET request that utilize query parameters to specify the given addresses, cost-methods, and page a request should be made for.

Now that we have that covered, let’s go through each of them and start setting up requests!

Making Requests

For this example, we’ll be utilizing Javascript to set up and make this request

First let’s get our request url

const baseUrl = 'https://api.openpool.co/wallet/accounting_history/'

Now let’s set up the request headers

Make sure you store your API key as an environment variable for security purposes.

const headers = {
    accept: 'application/json',
    'X-API-KEY': process.env.OPENPOOL_API_KEY
  }

Let’s now specify the addresses and timeframes for a given request

This process will be done through the use of query parameters appended to the request url that are defined as wallet (for addresses), and page
Addresses used here must be hexadecimal 0x strings
For example, to filter by address we’d utilize an address query param like so:

const addressToSearch = '0x59a5493513ba2378ed57ae5ecfb8a027e9d80365'

const baseUrlWithAddress = `https://api.openpool.co/accounting_history?wallet=${addressToSearch}`

To lookup multiple addresses, we’d just use a comma separated string for the respective addresses:

const address1ToSearch = '0x59a5493513ba2378ed57ae5ecfb8a027e9d80365'
const address2ToSearch = '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'

const stringOfCommaSeperatedAddresses = `${address1ToSearch}, ${address2ToSearch}`

const baseUrlWithAddresses = `https://api.openpool.co/wallet/balance/?wallet=`${stringOfCommaSeperatedAddresses}`

Now that we have all this down, let’s put together our request
In practice, you will likely want to use a more robust validation check here for the address

const retrieveTokenBalancesAndPerformance = async (address: string, timeframe = "W") => {
  if (!address || typeof address !== 'string' || address && typeof address === 'string' && !address.includes('0x')) {
    throw new Error('A valid address is required for making requests');
    return
  }
  try {
     let request = `https://api.openpool.co/wallet/balance/?wallet=${address}&period=${timeframe}`
     const headers = {
       accept: 'application/json',
      'X-API-KEY': '<YOUR_API_KEY>'
     }
    const requestOptions = {
      method: 'GET',
      headers: headers
    };

    const response = await fetch(url, requestOptions)
    const parsedResponse = await response.json()
    return parsedResponse
  }
  catch(e){
      console.error(`The error trying to retrieve address balances`, ${e})
  }
}

Reading from the response

When you receive a successful response, you will receive back an Object with 4 properties:

Results: An array of objects representing an enriched transaction positions that has the following shape:

[
   {
      "id": 26512775,
      "timestamp": "2021-11-09T14:55:29Z",
      "balance": "0.0088",
      "amount": "0.0088",
      "price": "4815.0046",
      "cash_flow": "42.1781",
      "fee_cash_flow": "0.0000",
      "basis": "42.1781",
      "realized_pnl": "0.0000",
      "wallet": "Wallet object (4)",
      "blockchain": {
        "id": 12,
        "name": "Ethereum",
        "slug": "ethereum",
        "image_url": "https://openpool.s3.amazonaws.com/landingImages/eth.png"
      },
      "token": {
        "id": 6178,
        "asset": {
          "id": 2,
          "name": "Ethereum",
          "symbol": "ETH",
          "slug": "ethereum",
          "image_url": "https://cdn.openpool.co/static/assets/ethereum.png"
        },
        "blockchain": {
          "id": 12,
          "name": "Ethereum",
          "slug": "ethereum",
          "image_url": "https://openpool.s3.amazonaws.com/landingImages/eth.png"
        },
        "token_id": "0x0000000000000000000000000000000000000000_12",
        "address": "0x0000000000000000000000000000000000000000",
        "decimals": 18
      },
      "basis_total": "42.17811371",
      "tx_id": "0x10b8d5bc4efa8f03f8e91531553164ce8f50556a9bda71221be0c396e697be61_0xaAcD601c5377ddf3F1f41eb1758bA0d2fA2b39BD"
    },
  ],

Count: The number of transactions listed on this page of the response
Next: The request URL for the next page of response
Previous: The request URL for the previous page of response

What’s next

Well, that’s up to you! You’ve now gone through how to access detailed financial accounting metrics for a given address that you can use either at work or in your next project. Go make some waves 🌊