How to Integrate with Heurist Mesh Agents for Token Analytics and Blockchain Data Retrieval

Integrate with Heurist Mesh agents by instantiating the MeshClient to send synchronous or asynchronous requests to specialized agent endpoints, using either explicit tool calls with structured arguments or natural-language query strings that the system's LLM automatically routes to the appropriate blockchain data retrieval functions.

The heurist-network/heurist-agent-framework provides a production-ready infrastructure for executing token analytics and blockchain queries through modular, LLM-driven agents. By leveraging the abstract MeshAgent base class and the lightweight MeshClient HTTP wrapper, developers can resolve token addresses, fetch market sentiment, and retrieve on-chain data without managing complex external API integrations or rate-limiting logic.

Architecture of the Heurist Mesh Framework

The framework centers on three core components that handle request routing, tool execution, and external API communication.

MeshAgent serves as the abstract base class in mesh/mesh_agent.py. It implements the generic request-handling pipeline, tool schema registration, LLM orchestration via call_gemini_with_tools_async(), timeout and fallback policies through _execute_tool_with_policy(), and a reusable _api_request() helper for HTTP operations.

Concrete agents inherit from MeshAgent and define task-specific logic. For blockchain and token analytics, the framework provides TokenResolverAgent, TokenMetricsAgent, and CoinGeckoTokenInfoAgent, each located in mesh/agents/. These classes override get_system_prompt(), get_tool_schemas(), and _handle_tool_logic() to implement specialized data retrieval workflows.

MeshClient in heurist-mesh-client/heurist_mesh_client/client.py provides the public integration surface. This thin HTTP wrapper manages authentication, formats request payloads for the Mesh server endpoints (/mesh_request for synchronous calls, /mesh_task_create and /mesh_task_query for asynchronous tasks), and handles environment-based API key loading.

Core Agents for Token Analytics and Blockchain Data

The framework includes specialized agents that aggregate data from DexScreener, CoinGecko, TokenMetrics, and other blockchain data providers.

TokenResolverAgent

Located in mesh/agents/token_resolver_agent.py, this agent resolves ambiguous token identifiers (addresses, symbols, or names) into canonical profiles. It exposes tools such as token_search and token_profile, which query DexScreener via _ds_search_pairs() and enrich results with CoinGecko metadata through _cg_get_token_info() and _enrich_with_profile_data(). The agent returns structured data including top DEX pools, market capitalization, price information, and official links.

TokenMetricsAgent

Found in mesh/agents/tokenmetrics_agent.py, this agent interfaces with the TokenMetrics API to provide quantitative analytics. Its tools include get_sentiments for general market sentiment analysis, get_resistance_support_levels for calculating technical price levels, and get_token_info for TokenMetrics-specific identifiers. The implementation uses _api_request() with the @with_cache decorator to optimize performance on frequently accessed endpoints.

CoinGeckoTokenInfoAgent

Defined in mesh/agents/coingecko_token_info_agent.py, this agent provides comprehensive CoinGecko Pro API coverage. Capabilities include retrieving full token information (get_token_info), trending coins, category data, multi-token price fetching, top holder statistics, historical holder charts, and large-trade snapshots. This agent is ideal for deep fundamental analysis and whale movement tracking.

Integration Patterns and Implementation

You can interact with these agents through three primary patterns: direct tool invocation for deterministic results, natural language queries for flexible LLM-driven routing, and asynchronous tasks for long-running analytics.

Direct Tool Calls for Structured Data

Use MeshClient.sync_request() with explicit tool and tool_arguments parameters when you require specific, reproducible data structures without LLM processing overhead.

from heurist_mesh_client import MeshClient

client = MeshClient(api_key="YOUR_HEURIST_API_KEY")

# Resolve a token by contract address on Base

result = client.sync_request(
    agent_id="token_resolver_agent",
    tool="token_search",
    tool_arguments={
        "query": "0xEF22cb48B8483dF6152e1423b19dF5553BbD818b",
        "chain": "base"
    },
    raw_data_only=True
)
print(result["data"]["results"])

# Fetch technical support levels for ETH from TokenMetrics

levels = client.sync_request(
    agent_id="tokenmetrics_agent",
    tool="get_resistance_support_levels",
    tool_arguments={"symbols": "ETH"},
    raw_data_only=True
)
print(levels["data"]["data"])

When raw_data_only=True, the agent skips the _respond_with_llm() formatting stage and returns raw JSON directly from _handle_tool_logic().

Natural Language Queries with LLM Orchestration

For conversational interfaces or ambiguous requests, supply a query string instead of explicit tool parameters. The agent's handle_message() method routes the prompt to Gemini via call_gemini_with_tools_async(), which selects the appropriate tools and arguments automatically.

from heurist_mesh_client import MeshClient

client = MeshClient(api_key="YOUR_HEURIST_API_KEY")

# LLM automatically selects get_sentiments and get_resistance_support_levels

response = client.sync_request(
    agent_id="tokenmetrics_agent",
    query="What is the current market sentiment for Solana and its key support levels?",
    raw_data_only=False  # Returns LLM-formatted natural language

)

print(response["response"])  # Human-readable analysis

print(response["data"])      # Raw tool outputs used for the response

The LLM uses the system prompt defined in the agent's get_system_prompt() method to constrain tool selection to the available schema, ensuring valid arguments for functions like get_sentiments or token_search.

Asynchronous Execution for Complex Workflows

For long-running analytics that may exceed HTTP timeout thresholds, use the asynchronous task endpoints implemented in MeshClient.create_task() and query_task().

import time
from heurist_mesh_client import MeshClient

client = MeshClient(api_key="YOUR_HEURIST_API_KEY")

# Create async task for comprehensive token profiling

task = client.create_task(
    agent_id="token_resolver_agent",
    tool="token_profile",
    tool_arguments={
        "coingecko_id": "solana",
        "include": ["pairs", "technical_indicators"]
    }
)

print(f"Task ID: {task.task_id}")

# Poll for completion

while True:
    status = client.query_task(task.task_id)
    if status.status.lower() != "pending":
        print(status.result)  # Final data payload

        break
    time.sleep(2)

This pattern posts to /mesh_task_create and polls /mesh_task_query, allowing the server to execute multiple _api_request() calls and data enrichment steps without maintaining a persistent HTTP connection.

Request Flow and Execution Pipeline

Understanding the internal request lifecycle helps optimize integration performance and error handling.

1. Client Initialization: MeshClient injects your API key into the headers of all requests to the Mesh server, supporting both explicit constructor arguments and the HEURIST_API_KEY environment variable.

2. Payload Routing: The server deserializes incoming JSON and instantiates the requested agent class. If the payload contains a tool field, the server immediately invokes _execute_tool_with_policy(), which applies per-tool timeouts and optional fallback agent logic before calling the concrete _handle_tool_logic() implementation.

3. LLM Routing: If only a query field is present, the agent sends the prompt to the configured LLM (Gemini by default). The LLM returns a structured tool call, which the agent executes through the same _execute_tool_with_policy() path.

4. External API Communication: All network requests flow through MeshAgent._api_request() (lines 57-78 in mesh_agent.py), which uses aiohttp for concurrency. If a 429 rate-limit occurs and the agent implements supports_proxy_fallback(), the request automatically retries through the proxy client defined in mesh/utils/proxy_client.py.

5. Caching Strategy: The @with_cache decorator applies TTL-based caching to _api_request() calls within each agent instance, reducing redundant traffic to external services like CoinGecko or TokenMetrics.

6. Response Formatting: When raw_data_only=False, the agent passes tool outputs to _respond_with_llm() to generate user-friendly explanations. When True, the raw data returns immediately after tool execution completes.

Summary

• Heurist Mesh provides a unified interface to specialized blockchain agents through the MeshClient class, eliminating the need to manage multiple external API integrations.
• TokenResolverAgent, TokenMetricsAgent, and CoinGeckoTokenInfoAgent offer comprehensive coverage for address resolution, market sentiment, technical indicators, and on-chain holder data.
• Integrate via direct tool calls (tool + tool_arguments) for deterministic, high-performance data retrieval, or use natural language queries (query) to leverage LLM-based tool selection and response formatting.
• Execute asynchronous tasks using create_task() and query_task() for complex analytics workflows that require extended processing time.
• All agents inherit robust error handling, caching, and rate-limit management from the MeshAgent base class in mesh/mesh_agent.py.

Frequently Asked Questions

How do I authenticate with the Heurist Mesh API?

The MeshClient class accepts an api_key parameter during instantiation or reads from the HEURIST_API_KEY environment variable. This key is automatically injected into the headers of all requests to the Mesh server endpoints, ensuring secure access to the agent infrastructure.

What is the difference between using a direct tool call and a natural language query?

Direct tool calls specify the exact tool name and tool_arguments dictionary, bypassing the LLM and executing _handle_tool_logic() immediately for faster, deterministic responses. Natural language queries provide a query string that the agent sends to Gemini via call_gemini_with_tools_async(), allowing the LLM to select appropriate tools and arguments dynamically before execution.

Can I use Heurist Mesh agents for real-time trading data?

Yes, agents like TokenResolverAgent fetch real-time DEX pair data from DexScreener and current price information from CoinGecko. However, consider using raw_data_only=True to minimize latency by skipping the _respond_with_llm() formatting step. For high-frequency requirements, implement your own polling logic using MeshClient.sync_request() rather than the asynchronous task endpoints.

How does the framework handle rate limits from external APIs like CoinGecko?

The MeshAgent._api_request() method automatically handles HTTP 429 responses. If an agent implements supports_proxy_fallback(), the framework routes the request through a proxy service defined in mesh/utils/proxy_client.py. Additionally, the @with_cache decorator reduces redundant calls by caching responses with configurable TTL values per endpoint.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}