Building a blockchain data-aware AI Agent

​

Introduction

In this tutorial, you will learn how to create in Shinkai a blockchain ecosystem data-aware AI Agent. Such an AI Agent would be able to talk about up-to-date blockchain data, including topics such as tokens and NFT data, DEXs activity and liquidity pools details, portfolio of addresses, stablecoin pegs, etc.

You will learn to :

• install blockchain related tools from Shinkai AI Store
• set up the AI Agent
• use the AI Agent
• deploy the AI Agent on different platforms
• build adequate Shinkai tools for such AI Agent (optional, more developer-oriented)

Our example will be a Cardano blockchain AI Agent, which accesses data through 6 related tools using the TapTools API. You can view the capabilities of this Cardano AI Agent in this video.

Parts 1, 2, and 3 of this tutorial cover setting up the AI Agent with existing Shinkai Tools and using it.

Part 4 is more developer-oriented and focuses on coding suitable tools for such AI Agents.

​

Prerequisites

To follow this tutorial effectively, you will need :

• the latest version of the Shinkai desktop App
• a TapTools API key if you want to test the example AI Agent and tools
• additional API keys for testing all the features (CoinMarketCap, ElevenLabs)

​

Part 1 : Using existing Shinkai tools

​

Installing the tools

Some blockchain related tools are already available in the Shinkai AI Store, and more are continuously being added.

In your Shinkai desktop App, navigate to the ‘Shinkai Tools’ tab, click on ‘Explore AI Store’, search for ‘TapTools’ or ‘Cardano’, and install the 6 following tools :

• Cardano Native Tokens Market Stats Aggregator
• Cardano NFT Market Stats Aggregator
• Cardano Native Token Trading Chart Generator
• Cardano Depeg Scanner
• Cardano Portfolio Tracker (tutorial to build it) :
• Cardano Native Token Analyzer

These tools retrieve real-time data on prices, market capitalization, trading volumes, NFT market activity, portfolio values, and more, providing outputs such as visualizations, CSV files, reports, and podcasts for customized blockchain data analytics.

​

Configuring the tools

For each tool, click on ‘Configure’, read the description, then navigate to ‘Configuration’. Depending on the tool, you can :

• enter relevant API keys
• activate/deactivate features
• include/exclude data from the tool results
• define options
• pick default values for some features

​

Part 2 : Setting up the AI Agent

Navigate to the ‘Agents’ tab, click on ‘Add Agent’, and set up your blockchain data-aware AI Agent.

First, define the persona of your Agent. Ensure you give it the desired personality and clear instructions on how to use its tools. Additionally, select a high-performing LLM capable of interpreting complex and potentially lengthy outputs (e.g., shinkai_free_trial, gpt_4_1).

Here is an example of instructions for our Cardano AI Agent, that includes the following :

• AI Agent personality
• rules for tools selection
• addition of Not Financial Advice warning

We use tags to separate elements and ensure clarity for the LLM.

<Personality>
You are Tappy, a polite, friendly, engaging and data-oriented cypherpunk penguin.
You are a specialist of the Cardano blockchain ecosystem, including NFTs, Native Tokens, stablecoins, synthetics, bridged assets, and portfolio tracking.
</Personality>

<Task>
Respond with accuracy to the user's message using the most appropriate tool you have access to, and the data from its output.
</Task>

<Instructions>
Be accurate, informative and clear.
You always use a tool before replying to a user.
Use one tool and only one tool at a time.
Use the most suitable tool according to the user’s message.
You always add a short friendly reminder that your answer is not a financial advice.
You have access to some knowledge document, use them if needed but don’t mention you are using it. Just use the information in your reply.
</Instructions

<Tool use>
You have access to 6 tools.
The tool "TapTools Cardano NFT Market Stats Aggregator" is about NFTs on Cardano.
The tool  “TapTools Cardano Depeg Scanner" is about stablecoin, synthetics, bridged coins or coins represented on Cardano (like Bitcoin and Ethereum), and peg or depeg scanning and alerts.
The tool “TapTools Cardano Native Token Analyzer” is about analyze a Cardano native token, using its ticker.
The tool “TapTools Cardano Portfolio Tracker” is about analyzing the portfolio of a particular Cardano wallet address.
The tool “TapTools Cardano Native Token Trading Chart Generator” is about creating chart for a given Cardano Native Token ticker.
The tool 'TapTools Cardano Native Tokens Market Stats Aggregator" is about market data for Native Tokens, with ranking by mcap or fdv, by liquidity, and by volume.
</Tool use>

In the ‘Knowledge’ tab you can add files that the AI Agent will always have in mind when answering users. You can for example include files describing the prominent projects, dApps, etc. of your blockchain of choice, or some trading technical analysis courses.

In the ‘Tools’ tab, activate all the blockchain tools your Agent needs.

In the ‘Schedule’ tab, you can set when your Agent will automatically run tasks.

Then save your AI Agent.

​

Part 3 : Using the blockchain AI Agent

​

3.1 Prompting well

To use your blockchain AI Agent effectively, thoroughly review the tools it accesses.

• The tool description outlines its features.
• The configuration shows some settings and options.
• The code and the inputs class show you what to include in your prompts to use the features of the tool.
• The metadata can show all the possible values for a given input.

Navigate to ‘Create AI Chat’ tab, click on the button to pick your AI, select your Agent in the top section.

The following are prompt examples for our Cardano AI Agent. These examples demonstrate how to trigger tools, include inputs in prompts, request specific information, specify data formatting, and interact easily with the blockchain AI Agent and its accessible data. Notice how each prompt includes somehow some keywords to help triggering the appropriate tool, and clearly states inputs when needed.

These prompts are from the preview screenshots of our TapTools Cardano tools available in the Shinkai AI Store. You can see most of the related answers from our Cardano AI Agents on these screenshots on their respective pages. Some prompts and answers can also be viewed in this demo video.

Here, we simply trigger the trading chart generator, giving clearly the values to use as inputs (ticker, candle_interval, num_intervals) :

Plot ticker IAG, 1d candles, 365 intervals

Here, we trigger the depeg scanner tool, mentioning “bridged” as it is one of the keywords for the tool :

How many BTC are bridged to Cardano ?

Here, we ask for data shown in table format :

Show me a table of USD stablecoins in Cardano.

Here, we ask for a precise information coming from the depeg scanner tool :

Show me the peg status of all BTC related coins on Cardano.

Here, in 1 prompt we ask for 2 different NFT rankings. The inputs used by this prompt are from the NFT market stats aggregator and are ‘Number_of_today_top_NFTs_to_retrieve’, ‘Ranking_method_for_today_top_NFTs’, ‘timeframe_for_top_NFTs_by_volume’, ‘Number_of_NFTs_per_page_for_top_NFTs_by_volume’.

Show me the top 20 NFTs by volume over the last 30d.
And rank today top NFTs by gainers, show top 15.

Here, we ask for a precise data (links) accompanied by more open data from an output, according to an input (all time).

Give me the links to check the all time top NFT collections by volume, show me their names and some quick stats too.

Here, we give both some precise inputs to use the portfolio tracker tool, and some instructions to comment the portfolio :

quote_currency : EUR
address : addrxxxxxxxxxxxxx
Analyse exhaustively the portfolio in great details, and then generate the text for a long and funny description of that wallet, making fun of the holder. For example, look into NFTs with ridiculously low value, into dust tokens, into poorly performing positions. Make sure to name the positions (name of the LP, of the ticker, of the NFT collection).

Here, we ask to focus on a part of the output of the token analyzer tool, and to also include some more information :

analyze ticker FLDT, for trading chart use 1d intervals, and 365 intervals,
focus your analysis on the holdings distribution,
and show me the links where I can know more about the project

Here, we give a rather open task, but with some format for the answer. This will use all the default inputs values as none is given :

write a full report on the current Cardano Native Tokens market

​

3.2 Deploying the AI Agent on different platforms

The Shinkai AI Store already offers tools to integrate with emails, X/Twitter and Telegram. You can then use some Scheduled Tasks to execute these tools regularly.

You can read this X/Twitter tutorial and watch this video. And you can find an example of Telegram bot deployment in the Cardano data AI Agent demo video here and here, as well as a detailed step-by-step guide in this NASA Agent demo.

Note that you can easily fork these tools and adapt the code to your needs. For example the default Telegram bot tool in the Shinkai AI Store answers to all new messages at once, but you can easily make it reply to each message one by one (as seen in the video demos).

You can stop reading this tutorial here. You should be now ready to implement new blockchain data-aware AI Agents in Shinkai.

The next part is more developer-oriented, and focuses on coding suitable tools for such AI Agents.

​

Part 4 : Building Shinkai Tools for a blockchain data-aware AI Agent

​

4.1 Choosing data sources

A blockchain AI Agent requires external source(s) of real-time on-chain data, as such up-to-date information is not part of the underlying LLM’s training data. The first step in designing the AI Agent is to choose appropriate sources of data to enable the desired capabilities of the AI Agent.

Possible sources of live on-chain data include :

• local indexer with data fetching capabilities :

The blockchain AI Agent would get data by querying directly your local indexer, most likely linked to your local node. For Cardano, such indexers include : kupo, koios, utxorpc, cardano-graphql, among others. The Agent tools would then format the data as needed. Such indexers might also be hosted by service providers.

• blockchain data provider services :

The blockchain AI Agent would get data by calling API endpoints from specialised data providers. These providers typically run their own nodes and format data on top of raw on-chain data. For Cardano, such platforms include Maestro, Blockfrost, TapTools.

• decentralized blockchain data protocols :

The blockchain AI Agent would get data by accessing organized data that is structured and indexed through a decentralised blockchain data protocol. Such data sources include for example The Graph Protocol.

• crypto wide analytics and market platforms :

The blockchain AI Agent would get data by querying formatted data from platforms specialised in blockchain analytics about protocols, valuations, etc. Such platforms include DeFiLlama, CoinGecko, etc.

To guide your choice of data sources and of precise data, think about the content and the format of the information you want your blockchain AI Agent to be able to output.

In this tutorial we use the TapTools API. TapTools is the dominant platform for data about Cardano tokens and NFTs trading as well as wallet tracking. Our Cardano AI Agent uses tools that call TapTools API endpoints, then process and format the data to create useful outputs interpretable by the AI Agent.

​

4.2 Defining tools

To create an advanced blockchain data AI Agent with various capabilities, you will need multiple tools. Based on the user’s prompt, the AI Agent will use the most appropriate of its tools to answer and execute the required task(s). This leads to some requirements.

Tools should be :

• standalone :

Each tool should provide a unique but complete set of capabilities and/or data. This will ensure that when the AI Agent uses a given tool it will have all it needs to perform the corresponding task completely.

• distinct and easy to trigger :

It should be easy for the AI Agent to know with high accuracy which tool to use for a given task.

​

4.3 Choosing precise data points for each tool

Once you have identified tools to give your blockchain AI Agent robust capabilities, you can map the specific data each tool will acquire.

For example, for tools relying on API calls, you can create a spreadsheet for each tool, listing all useful endpoints, their outputs, and the use cases they enable. This will help you being exhaustive and making full use of the accessible data, to give rich features to your AI Agent.

For example, here are the endpoints of the TapTools API used for our Cardano Native Token Analyzer tool :

This variety of data allows the Cardano AI Agent to trigger only one tool when asked about a particular token while being able to answer various questions and provide extensive analysis.

Once you have defined your blockchain AI Agent’s tools, you can build them carefully following the guidance below to make them optimally useful.

​

4.4 Building useful tools

AI Agent tools have keywords to trigger them, configurations to set features, inputs/parameters to perform specific tasks, and various possible outputs.

To maximize their usefulness, tools must :

• have easy to use inputs
• have explicit outputs
• be efficient : eventually have some optional features
• explore useful multimodal outputs
• have guided outputs interpretation
• have granular error handling

For the tools of a blockchain AI Agent, this can translate to : ensuring sorting parameters and timeframes are easy to use when asking about NFTs or tokens trading activities, making it clear for the LLM what each data like holdings, volumes, sales, etc. is about, have some deeper and more compute-heavy analysis optional (like holders distribution analysis), allowing for graphs of trading activity and portfolio positions or even creating podcasts about tokens, adding some warnings and considerations over the specifics of some data points like supplies and top holders which might include special wallets, and more.

Below, you can explore these aspects through code examples from our TapTools Cardano tools. You can also read the step-by-step tutorial to build a portfolio tracker tutorial, which includes a fully annotated code.

​

4.4.1 Easy to use inputs

Inputs should be well defined and distinct. For example, users are likely to ask questions to a blockchain AI Agent over different timeframes. However, a tool with too many timeframe inputs might confuse the AI Agent’s LLM, especially if timeframe names are too similar.

In our NFT market stats tool, we use 3 different timeframe inputs for different data, and we make sure their names are explicit and distinct :

class INPUTS:
    timframe_for_NFT_market_stats: Optional[str] = "30d"
    timeframe_for_top_NFTs_by_volume: Optional[str] = "24h"
    timeframe_for_NFT_volume_trended: Optional[str] = "30d"

To maximize user-friendliness, set default timeframe values to the most relevant or frequently used timeframes, so that users don’t need to include any timeframe information in their prompts if they are happy with the default value. Alternatively the default value of any input could also be choosable as a configuration, so that users can define their own.

All inputs should have explicit names, not only for the LLM to be able to match elements of the users’ prompts with the corresponding inputs to use, but also for the users to easily know what parameters the tool has, and so to know what to include in their prompts.

In our TapTools tools, the API endpoints have parameters with generic names. So we create inputs with more explicit names and pass them as parameters for the API calls.

Below is an example for the ranking method of today top NFTs. The parameter for the endpoints is simply ‘ranking’, but we create a more explicit input :

class INPUTS:
    Ranking_method_for_today_top_NFTs: Optional[str] = "volume"

We then use this value in the corresponding endpoint call.

async def run(config: CONFIG, inputs: INPUTS) -> OUTPUT:
    api_base_url = "https://openapi.taptools.io/api/v1"nft_market_stats_url = f"{api_base_url}/nft/market/stats/extended?timeframe={inputs.timframe_for_NFT_market_stats}"
    top_nfts_url = f"{api_base_url}/nft/top/timeframe?ranking={inputs.Ranking_method_for_today_top_NFTs}&items={inputs.Number_of_today_top_NFTs_to_retrieve}"

​

4.4.2 Explicit outputs

The way AI Agent tools work is that their outputs are passed as context to the LLM behind the AI Agent. It is content added to the users’ prompts. For a blockchain AI Agent, we must ensure all data from the tools is clear and unambiguous. This means naming explicitly all elements of the outputs, adding units (in some cases dynamically), making % obvious, etc. Below are some examples.

For example, in the portfolio tracker tool, we create an output ‘portfolio_positions’ as a dictionary, to then edit its components :

class OUTPUT:
    portfolio_positions: Dict[str, Any]

We rename all the keys before including them in that output :

    # Fetch portfolio positions
    response = get(portfolio_positions_url, headers=headers)
    
    output = OUTPUT()
    
    if response.status_code == 200:
        data = response.json()
        
        # Rename keys
        data["Number_of_Fungible_Tokens"] = data.pop("numFTs", 0)
        data["Number_of_NFT_collections"] = data.pop("numNFTs", 0)
        data["Fungible_Tokens_positions"] = data.pop("positionsFt", [])
        data["NFTs_positions"] = data.pop("positionsNft", [])
        data["Liquidity_Provider_Positions"] = data.pop("positionsLp", [])

We improve the formatting of some data coming as percentages. The API endpoints deliver % as number with many decimals. To improve clarity, we multiply by 100, round to two decimals, add a ’%’ symbol, and include a ’+’ symbol for positive percentages.

        # Modify percentages and calculate quote currency values
        for position in data["Fungible_Tokens_positions"]:
            for timeframe in ["24h", "7d", "30d"]:
                if timeframe in position:
                    change_value = position[timeframe]
                    sign = "+" if change_value >= 0 else ""
                    position[timeframe] = f"{sign}{round(change_value * 100, 2)} %"

Rounding token prices can also require some care to be meaningfully presented, as they can be from in the thousands to incredibly small decimal numbers below 1. Below we format to 2 decimals if price is above 1, or to 10 decimals max with up to 3 non-zero numbers if below 1.

def format_price(price: float) -> str:
    """Format price based on its value."""
    if price >= 1:
        return f"{price:.2f}"
    else:
        price_str = f"{price:.10f}".rstrip('0')
        decimal_idx = price_str.index('.')
        for i in range(decimal_idx + 1, len(price_str)):
            if price_str[i] != '0':
                end_idx = min(i + 3, len(price_str))
                return price_str[:end_idx]
        return price_str

Below we dynamically name the outputs of a token price, fdv and market cap in quote currency, and add that quote currency, to make it super clear.

    token_asset_data.update({
        f"{inputs.ticker}price_in_{config.quote_currency}": f"{format_price(ticker_price_in_quote)} {config.quote_currency}" if ticker_price_in_quote else None,
        f"{inputs.ticker}fully_dilluted_valuation_in_{config.quote_currency}": f"{round(ticker_fdv_in_quote)} {config.quote_currency}" if ticker_fdv_in_quote else None,
        f"{inputs.ticker}market_cap_in_{config.quote_currency}": f"{round(ticker_mcap_in_quote)} {config.quote_currency}
        ...

You should also remove from the output some data coming from the data sources but that you’re not interested in. This will improve speed and lower the cost of the LLM inference. Below, we remove 2 data points from the output of our portfolio tracker tool (unit and fingerprint of the token) :

            position.pop("unit", None)
            position.pop("fingerprint", None)

​

4.4.3 Exploring multimodal outputs

Because they use tools, blockchain AI Agents are not limited to text-based outputs. Some prices evolution or holdings data might be better shown on a graph. Some token analysis might be usefully presented in a pdf report. Some information might be more efficient to listen to instead of reading. Shinkai tools are highly composable, and you can easily add capabilities by integrating an existing tool to your blockchain tool. A basic example would be integrating a text to speech tool for audio output.

Our Cardano Native Token Analyzer tool is able to generate a trading chart, a Lorenz curve graph for holdings distribution analysis, a full pdf report, and a few minutes long podcast about a token.

Below is the code where we generate a podcast script for a token analysis. It uses the output ‘token_data’ which contains all the data gathered by the tool for a given token, as well as the config ‘podcast_script_instructions’, and the LLM prompt processor tool :

    # Podcast Script Generation
    if config.generate_podcast_script.lower() == "yes":
        try:
            podcast_input = {
                "format": "text",
                "prompt": (
                    "You are the writer of the podcast Tappy Chats, which is about detailed and insightful Cardano blockchain data."
                    "Using all of the information from the output token_data below, generate a podcast script according to the instructions below."
                    "Make sure to talk about every section of token_data."
                    "When analyzing value, only use Ada or USD or Euro value, not the value in the amount of the token."
                    "<information from output token_data>"
                    f"{token_data}"
                    "</information from output token_data>"
                    "<instructions>"
                    f"{config.podcast_script_instructions}"
                    "</instructions>"
                    "<format instructions>"
                    "Handle numbers gracefully. If you throw too many numbers at the listeners you can lose them. So pick relevant numbers."
                    "Make sure to round numbers to make them clearer to hear and understand. For tiny numbers with many zeros below zero, you can use 'less than a cent', or 'much less than a cent'."
                    "The text must flow. Do not use any formatting, but just plain text. The text should just be one flowing paragraph."
                    "</format instructions>"
                )
            }
            podcast_script = (await shinkai_llm_prompt_processor(podcast_input)).get("message")
        except Exception as err:
            error_messages.append(f"Podcast script generation failed: {err}")
    else:
        status["podcast_script"] = "Skipped (set to 'no')"

The podcast_script output is then passed to a text to speech tool.

    # Audio Generation
    if config.generate_audio.lower() == "yes":
        if podcast_script:
            try:
                home_path = await get_home_path()
                audio_file_name = f"tappy_chats_{inputs.ticker}.mp3"
                # Call the integrated eleven_labs_text_to_speech function
                audio_generation_result = await eleven_labs_text_to_speech(
                    {"text": podcast_script, "fileName": audio_file_name},
                    {"ELEVENLABS_API_KEY": config.ELEVENLABS_API_KEY, "voice": config.voice}  # Pass config
                )
                audio_file_path = audio_generation_result['audio_file'] # Use the returned path
            except Exception as err:
                error_messages.append(f"Audio generation failed: {err}")
        else:
            error_messages.append("Cannot generate audio: podcast script missing.")
    else:
        status["audio_generation"] = "Skipped (set to 'no')"

​

4.4.4 Be efficient, have some optional features

Users may not need all the capabilities of a blockchain AI Agent’s tool every time they interact with it. Maybe sometimes the user just wants to do a quick check on a specific data point. So while each tool can offer different features, it is worth it to think about which ones would be used often, and which ones could be optional. You then must decide which options should be activated in configuration, and which ones should be activated using inputs (allowing users to activate them within their prompts).

Optional features enable a tool, and thus an AI Agent, to be :

• easier to use :

In configuration the user activates / deactivates the desired options, and don’t have to include such information in their prompts each time. And if an optional feature must be activated through an input, setting the default to the most often used also allows users to not include that option information in their prompts all the time.

• faster :

The tool is not processing something the user is not actually using.

• cheaper :

The inference cost is lower because the LLM of the AI Agent is processing smaller information.

Below is the configuration of optional outputs in our Cardano Native Token Analyzer tool :

class CONFIG:
    show_trading_chart: str = "no"  # "yes" or "no"
    create_pdf_report: str = "no"   # "yes" or "no"
    generate_llm_report: str = "no" # "yes" or "no"
    generate_podcast_script: str = "no" # "yes" or "no"
    analyze_holder_distribution: str = "no" # "yes" or "no"
    generate_audio: str = "no" # "yes" or "no"
    show_llm_report_content: str = "no" # "yes" or "no"

And here is for example the optional triggering of the holders distribution analysis, with 2 different error messages in case of analysis failure or simply deactivated option :

    # Optional Features
    # Holder Distribution Analysis
    if config.analyze_holder_distribution.lower() == "yes":
        try:
            holder_analysis_data, holder_graph_path = await analyze_holders(unit, inputs.ticker, taptools_headers, endpoints, ticker_price_in_ada, ticker_price_in_quote, config.quote_currency)
            token_data[f"{inputs.ticker}_holder_distribution"] = holder_analysis_data
        except Exception as e:
            error_messages.append(f"Holder distribution analysis failed: {e}")
    else:
        status["holder_distribution_analysis"] = "Skipped (set to 'no')"

To note, optional outputs can rely on other optional outputs. You should therefore make sure the tool’s conditional logic is correct, and has good (error) messaging.

A tool should not globally fail if some options are deactivated. A tool should indicate if some options are missing for a certain feature to be executed.

Here is an example of the Cardano Native Token Analyzer tool outputs clearly showing the state of each optional feature :

  "audio_file_path": null,
  "chart_file_path": "C:\\Users\\gille\\AppData\\Roaming\\com.shinkai.desktop\\node_storage\\tools_storage\\app-id-1741695406055\\home\\HOSKY_chart.png",
  "error_message": null,
  "holder_graph_path": null,
  "llm_report": null,
  "pdf_file_path": null,
  "podcast_script": null,
  "status": {
    "audio_generation": "Skipped (set to 'no')",
    "holder_distribution_analysis": "Skipped (set to 'no')",
    "llm_report": "Skipped (set to 'no')",
    "pdf_report": "Skipped (set to 'no')",
    "podcast_script": "Skipped (set to 'no')"
  },

And here we create a function to validate the configuration, and use it to stop the tool quickly if there are issues.

def validate_config(config: CONFIG) -> List[str]:
    """
    Validate configuration flags and dependencies.
    Returns a list of error messages if any issues are found.
    """
    errors = []
    flags = [
        "show_trading_chart", "create_pdf_report", "generate_llm_report",
        "generate_podcast_script", "generate_audio", "analyze_holder_distribution"
    ]
    for flag in flags:
        value = getattr(config, flag)
        if value.lower() not in ["yes", "no"]:
            errors.append(f"Invalid config value for {flag}: {value}. Must be 'yes' or 'no'.")

    if config.generate_audio.lower() == "yes" and config.generate_podcast_script.lower() != "yes":
        errors.append("Cannot generate audio without generating podcast script. Set generate_podcast_script to 'yes'.")
    return errors

    # Validate configuration and fail fast if there are issues
    config_errors = validate_config(config)
    if config_errors:
        return OUTPUT(error_message="; ".join(config_errors))

​

4.4.5 Guided outputs interpretation

Blockchain data might need some extra explanation, context, note, consideration or even warning when given to the users.

To ensure your blockchain AI Agent delivers highly informative data, you can hardcode notes in its tools’ outputs. They will be included in the context window when the LLM of the AI Agent uses the tools to answer the users’ prompts, and will ensure the data is introduced with some precisions you care about.

Below are examples of notes added to some metrics in our Cardano Native Token Analyzer tool.

In the token distribution analysis, we inform users that raw top on-chain addresses analysis might include special wallets still belonging to the project, and we explain more about the small holder ratio.

    return {
        f"{ticker}_onchain_address_concentration_top_10": f"{concentration_top_10:.2f} % of the {ticker} token total supply is held by the top 10 on-chain addresses (WARNING: this might include special wallets like project wallets of non-circulating supply, liquidity pools on DEXs, etc.).",
        f"{ticker}_small_onchain_address_ratio": f"{small_holder_ratio:.2f} % of the on-chain addresses holding {ticker} hold less than {CONFIG.small_holder_ratio_threshold}% of the total supply. This metric shows how much of the community consists of small retail investors versus big players, reflecting grassroots support. (WARNING: this metric could be affected by addresses with residual amounts.)",
        ...

​

4.4.6 Granular error handling

Tools should record errors separately for each feature and not fail globally if only one or some features fail. Error messages should be clear, informative, and included in the outputs so the AI Agent can effectively inform users about any issues encountered.

If using an API, make sure the tool accesses and outputs the original detailed error message of the endpoint :

    # Fetch the price of ADA in the specified quote currency
    quote_response = get(token_quote_url, headers=headers)
    if quote_response.status_code != 200:
        output = OUTPUT()
        try:
            error_details = quote_response.json()
            error_message = error_details.get("message", "An error occurred")
        except json.JSONDecodeError:
            error_message = quote_response.text
        output.error = f"Error fetching ADA price: {error_message} (Status Code: {quote_response.status_code})"
        return output

You can also create error_message and status outputs to track errors and different states.

class OUTPUT:
    error_message: Optional[str]
    status: Optional[Dict[str, str]] 

    # Initialize error messages and status tracking
    error_messages = []
    status = {}

And then you add eventual errors and status one by one :

        except Exception as e:
            error_messages.append(f"Holder distribution analysis failed: {e}")
    else:
        status["holder_distribution_analysis"] = "Skipped (set to 'no')"

And you output them :

    return OUTPUT(
        ...
        error_message="; ".join(error_messages) if error_messages else None,
        status=status if status else None
    )

​

Support and sharing your tools

The possibilities and enhancements for tools are vast and easily implemented in Shinkai thanks to its AI-assisted tool builder.

For additional support in your tool creation journey, please contact Shinkai Tools support team or join us and the community on our Discord server. Engage with the community to share your tools and ideas.