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

> Integrate Heurist Mesh agents for token analytics and blockchain data retrieval. Use MeshClient to send queries or tool calls for efficient data access and analysis.

- Repository: [Heurist/heurist-agent-framework](https://github.com/heurist-network/heurist-agent-framework)
- Tags: how-to-guide
- Published: 2026-03-03

---

**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`](https://github.com/heurist-network/heurist-agent-framework/blob/main/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`](https://github.com/heurist-network/heurist-agent-framework/blob/main/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`](https://github.com/heurist-network/heurist-agent-framework/blob/main/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`](https://github.com/heurist-network/heurist-agent-framework/blob/main/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`](https://github.com/heurist-network/heurist-agent-framework/blob/main/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.

```python
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.

```python
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()`.

```python
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`](https://github.com/heurist-network/heurist-agent-framework/blob/main/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`](https://github.com/heurist-network/heurist-agent-framework/blob/main/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`](https://github.com/heurist-network/heurist-agent-framework/blob/main/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`](https://github.com/heurist-network/heurist-agent-framework/blob/main/mesh/utils/proxy_client.py). Additionally, the `@with_cache` decorator reduces redundant calls by caching responses with configurable TTL values per endpoint.