Building a Blockchain Address Portfolio Tracker tool
Introduction
In this tutorial, we will build a cryptocurrency address portfolio tracker, as a Shinkai Tool. This tool can be a core component of a crypto AI Agent able to talk about up-to-date blockchain data. The tool presented here interacts with the TapTools API to analyze and visualize portfolio data for a specified Cardano wallet address. It retrieves positions for fungible tokens, NFTs, and liquidity provider positions, calculates their values in Ada and in a specified quote currency, and can generate visualizations based on user-defined parameters.
You can find this tool in the Shinkai AI Store. Its name is : Taptools Cardano Portfolio Tracker. You can watch one usage example of this tool here.
While we use a Cardano example, the same tool structure can be applied to any blockchain for which an API provides such data.
Prerequisites
Before you begin, ensure you have :
- the latest version of the Shinkai Desktop App installed
- the App open at the tool creation UI
- a Taptools API key
Step 0 : Working prototype tool using the Shinkai AI assisted tool creation UI
Shinkai allows effortless building of tools and AI Agents thanks to its integrated in AI assistance. You can build the tool by just prompting a LLM. With Shinkai, you don’t have to wrestle with library dependencies or handle manual deployments, everything is automated and user-friendly.
In this video we build in just a few minutes a working prototype of the Cardano portfolio tracker tool data retrieval feature, by simply providing instructions and including snippets of the API documentation.
This prompting process was used to build all the features of the tool, with some manual improvements of the code.
Below, we go over the full code in details.
Step 1 : Import components
We import ‘get’ to make API calls. We import ‘matplotlib’ to create graphs. We import ‘get_home_path’ to save some files.
Step 2: Define Configuration Class
We start by defining a configuration class to hold our settings :
- the TapTools API key
- some minimum positions value to filter out small ones from graphs
Step 3: Define Input Class
Next, we define an input class to capture user inputs :
- the address to look at
- the quote currency to use
- some flags to generate or not some plots
- the timeframe to use for the chart of the porfolio value over time
These flags will be used for optional outputs: the user can choose whether to generate plots and graphs by setting the generate_positions_plots and generate_portfolio_trended_value_graphs attributes.
Step 4: Define Output Class
We create an output class to structure the data returned by our tool.
The error field is included only if an error occurs during API calls.
Step 5: Start of the Main Function to Run the Tool
Now we implement the run function, which encapsulates the main logic of our tool.
Multiple API Calls: this function makes 2 API calls to fetch data, one for portfolio positions and one to get the quote price of Ada, so that we can convert all positions value to a quote currency.
Step 6: Fetching ADA Price
The first API call retrieves the price of ADA in the specified quote currency.
Error Handling: If the API call fails, the tool captures the error message and returns it in the output.
And we store the Ada price.
Step 7: Fetching Portfolio Positions
Next, we fetch the portfolio positions using another API call, and store it in ‘data’.
Step 8: Improving the output
8.1: Renaming Keys
Once we have the data, an important step is to give explicit names to keys for clarity. Well formatted outputs will help the LLM interpreting the data to better answer the users’ prompts.
8.2: Formatting % changes for fungible tokens positions
We improve the formatting of percentage changes by multiplying by 100, rounding, and adding + sign if positive.
8.3: Rounding values and calculations in quote currency
For better formatting, we round some values. We also calculate some values in quote currency. Note the dynamic naming of the output key : using inputs.quote_currency allows to set the name according to the selected quote currency in inputs.
8.4: Clearing the output of unneccessary elements
We remove data from the output that comes from the API call but is not of interest (unit and fingerprint of the token).
We repeat the above for NFTs positions :
And for liquidity provider positions, we also round and calculate values in quote currency.
We also improve the output part about the total value. We calculate it in quote currency, and improve the naming plus round.
Step 9: Generating Plots for the different positions
If requested, the tool generates plots for fungible tokens, NFTs, and liquidity provider positions.
We make the plot generation conditional.
We set a dark background for all plots.
We convert our config parameters to float
We build 3 barplot graphs (NFTs, tokens, liquidity provider positions).
Note these 2 lines at the beginning of each graph, which allows to filter out some of the positions if they are below the minimum thresholds set in configurations.
Step 10: Generating Trend Graphs
Finally, if requested, we can generate trend graphs based on the portfolio value over time. We call the corresponding endpoint twice, once for the value in Ada and once for the value in quote currency. We generate a graph for each.
The rest of the code logs errors and returns the output.
Feel free to extend this tool further by adding additional features or integrating with other APIs!
Screenshots
Below are 4 screenshots of our portfiolio tracker tool being used in Shinkai.
Was this page helpful?