Setting Up Natural Language Queries for On-Chain Data Analytics

Natural language query (NLQ) systems translate human questions into structured queries that a blockchain indexer can understand. Instead of writing SELECT * FROM ethereum.transactions WHERE block_number > 15000000, you can ask "Show me the latest high-value transactions on Ethereum." This is powered by large language models (LLMs) that parse intent and map it to on-chain data schemas. Services like Chainscore, The Graph's Natural Language API, and Flipside Crypto's AI Assistant provide these interfaces, abstracting the underlying complexity of subgraphs or raw RPC calls.

Setting up NLQ typically involves connecting to an API endpoint with your query and receiving structured JSON data. For example, using Chainscore's API, you might send a POST request with a prompt like "Get the top 10 NFT collections by volume on Polygon last week." The system identifies the required data points—collection addresses, sale volumes, timestamps—and executes the corresponding query against its indexed dataset. You need an API key from the provider and basic knowledge of making HTTP requests from your application or a script.

For developers, integrating NLQ starts with choosing a provider based on supported chains, data freshness, and cost. Most offer a free tier for testing. A basic integration in Python using the requests library looks like this:

pythonCopy
import requests
api_key = 'YOUR_API_KEY'
url = 'https://api.chainscore.io/v1/nl-query'
headers = {'Authorization': f'Bearer {api_key}'}
data = {'query': 'What is the current TVL of Aave v3 on Arbitrum?'}
response = requests.post(url, json=data, headers=headers)
print(response.json())

The response will contain the Total Value Locked figure and often additional context like the underlying query used.

Key considerations when using NLQ systems include query specificity and cost management. Vague questions may return ambiguous results, so refining prompts (e.g., "TVL in USD" vs. "TVL") improves accuracy. Since each query consumes API credits, it's efficient to batch related questions. Furthermore, always verify critical data points, as LLMs can occasionally "hallucinate" or misinterpret niche terminology. For production use, implement caching for frequent queries to reduce latency and cost.

The primary use cases are exploratory data analysis, dashboard prototyping, and automated reporting. An analyst can quickly investigate wallet activity or protocol metrics without writing SQL. A developer can embed NLQ features into an application to let users ask questions about their portfolio. This technology significantly lowers the barrier to on-chain analytics, but it complements rather than replaces deep, custom querying for complex, high-frequency data needs.

Natural language querying for blockchain data requires a specific technical stack. You will need a working knowledge of JavaScript/TypeScript and Node.js (v18 or later). Familiarity with Ethereum concepts like smart contracts, addresses, and common data standards (ERC-20, ERC-721) is essential. For the initial setup, ensure you have npm or yarn installed to manage dependencies. This guide uses the Chainscore API as the primary interface, which translates English questions into structured queries for protocols like Ethereum, Arbitrum, and Base.

The first step is to obtain your API credentials. Navigate to the Chainscore Developer Portal and create an account to generate an API key. This key authenticates your requests and manages rate limits. Store it securely using environment variables. Create a .env file in your project root and add your key: CHAINSCORE_API_KEY=your_key_here. You can then install the necessary Node.js client library using npm install @chainscore/chainscore.

With the library installed, you can initialize the client in your application. Import the Chainscore class and instantiate it with your API key. The client is your gateway to submitting queries. For example, a basic initialization script looks like this:

javascriptCopy
import { Chainscore } from '@chainscore/chainscore';
const chainscore = new Chainscore({
  apiKey: process.env.CHAINSCORE_API_KEY,
});

This client object will be used to call methods like chainscore.query("Your question here") to fetch on-chain data.

Your queries will target specific blockchain networks. You must configure the chain ID for your data source. Common IDs include 1 for Ethereum Mainnet and 42161 for Arbitrum One. The Chainscore API supports multiple chains, allowing you to analyze data across ecosystems. When formulating a question, clarity is key. Instead of "show me some swaps," ask "What were the top 5 Uniswap V3 swaps by USD volume on Arbitrum in the last 24 hours?" This specificity helps the engine return accurate, actionable results.

Finally, consider the output format. The API returns data in structured JSON, which you can integrate into dashboards, trading bots, or research tools. You may want to set up a simple Express server or a script to periodically fetch and process this data. Understanding these prerequisites—the development environment, API access, client setup, and query formulation—ensures a smooth start to building powerful on-chain analytics with natural language.

A natural language query (NLQ) system for blockchain data requires a multi-layered architecture to bridge the gap between human language and structured on-chain information. The core components are: a user interface for input, a natural language processing (NLP) engine to interpret intent, a query translation layer that maps concepts to on-chain data schemas, and a data indexing and retrieval layer that executes the query against a processed dataset. This architecture abstracts the complexity of raw blockchain data, allowing users to ask questions like "What was the total volume on Uniswap V3 yesterday?" without writing SQL or interacting with low-level RPC calls.

The data flow begins when a user submits a question. The NLP engine, typically powered by a large language model (LLM) like GPT-4 or an open-source alternative, performs intent classification and named entity recognition. It identifies key entities (e.g., "Uniswap V3", "volume", "yesterday") and the user's goal (e.g., aggregate a metric). The output is a structured intermediate representation, often in JSON, that defines the what, where, and when of the query. For reliability, this stage may use few-shot prompting with examples of successful translations to guide the model.

The query translation layer is the critical bridge. It takes the structured intent and maps it to a specific data schema and query language. If your indexed data is in a PostgreSQL data warehouse, this layer generates SQL. If you're querying a subgraph on The Graph, it constructs a GraphQL query. This requires a schema definition that the system understands—a metadata layer describing available tables, fields, and their relationships to blockchain concepts (e.g., mapping 'swap' to a dex.trades table). Tools like LangChain or LlamaIndex are often used here to create this abstraction and manage context.

Finally, the generated query executes against a pre-indexed data layer. Querying raw Ethereum blocks via an RPC is too slow for analytics. Instead, systems rely on indexed data providers like The Graph, Dune Analytics, Covalent, or custom pipelines using Apache Spark or ClickHouse. The result is returned, often formatted by the LLM into a human-readable answer (e.g., "The total volume was $125.4M"). For production systems, implementing a caching layer for frequent queries and query validation to prevent malformed or expensive operations is essential for performance and cost control.

When implementing this architecture, key decisions include choosing between a general-purpose LLM API (easier setup, ongoing cost) and a fine-tuned open-source model (more control, higher initial effort), and selecting your data index. For Ethereum, using Dune's Spark SQL engine or The Graph's subgraphs provides robust, community-vetted schemas. A practical first step is to prototype using the OpenAI API with LangChain's SQL Agent, connecting it to a public Dune API endpoint or a mirrored dataset to handle the translation and execution automatically, demonstrating the end-to-end flow.

In on-chain analytics, prompt engineering transforms ambiguous user questions into structured queries a system can execute. The core challenge is intent recognition—determining if a user wants a wallet's balance, an NFT's floor price, or a token's trading volume—and entity recognition—identifying the specific addresses, token symbols, or contract names involved. A well-designed prompt acts as an instruction set for a language model, guiding it to parse natural language and output a standardized query format like GraphQL or SQL.

Start by defining the core user intents your system supports. Common intents in DeFi and NFT analytics include: get_balance, get_transactions, get_token_price, get_pool_stats, and get_holder_distribution. For each intent, specify the required and optional entities. For example, the get_balance intent requires an address entity and a token_symbol or chain entity. Document these in a schema that maps intents to their expected parameters and data sources, such as The Graph subgraphs or direct RPC calls.

Craft your system prompt to explicitly instruct the LLM on this schema. Use few-shot prompting with clear examples to demonstrate the input-output mapping. For instance: User: "What's the ETH balance for vitalik.eth?" System: {"intent": "get_balance", "entities": {"address": "vitalik.eth", "token_symbol": "ETH"}} User: "Show me the last 10 transactions for the Uniswap V3 factory." System: {"intent": "get_transactions", "entities": {"contract_address": "0x1F98431c8aD98523631AE4a59f267346ea31F984"}, "parameters": {"limit": 10}}. This teaches the model the expected JSON structure.

Handle ambiguity and errors by designing prompts that encourage the model to ask clarifying questions or return confidence scores. If a user asks "What's the price of APE?", the prompt should instruct the model to recognize APE could refer to ApeCoin (0x4d224452801aced8b2f0aebe155379bb5d594381) or the NFT collection Bored Ape Yacht Club. Your prompt might include a disambiguation step: "If a token symbol is ambiguous, return a list of possible contract addresses for the user to choose from."

Finally, integrate the parsed output into your data pipeline. The structured JSON from the LLM should trigger a specific query function. For the get_pool_stats intent for a DEX like Uniswap, you would use the extracted pool_address to call a subgraph query fetching totalValueLocked, volumeUSD, and feesUSD. Always validate extracted entities—confirm an address is valid on the specified chain using libraries like ethers.js or viem before querying to prevent errors and enhance security.

Setting up natural language queries transforms blockchain analytics from a developer-centric task to an accessible tool for researchers, analysts, and product teams. The core architecture you've implemented involves three layers: a data indexing layer (using services like The Graph or Subsquid), a vector database (like Pinecone or Weaviate) for semantic search on indexed schemas, and an LLM orchestration layer (via LangChain or LlamaIndex) to translate user questions into executable queries, such as GraphQL or SQL. This setup allows questions like "Show me the top 10 NFT minters on Ethereum last week" to be processed automatically.

For production deployment, several critical next steps are required. First, implement rigorous query validation and sanitization to prevent malicious or malformed inputs from reaching your indexers. Second, establish a feedback loop where users can flag incorrect LLM translations, which you can use to fine-tune your prompts or create a curated set of few-shot examples. Third, consider cost optimization by caching frequent query patterns and implementing usage limits, as LLM API calls and complex indexer queries can become expensive at scale. Tools like Prometheus for monitoring and Grafana for dashboards are essential for tracking system performance and costs.

To extend your system's capabilities, explore integrating more data sources. Consider adding real-time data streams from WebSocket connections to nodes for sub-second analytics, or off-chain data from oracles like Chainlink to enrich context. You can also build specialized agents that not only query data but execute actions based on the results, such as triggering a smart contract or sending an alert. The foundational pattern you've built—translating intent into structured query—is the first step toward more autonomous, intelligent blockchain applications. Continue experimenting with different LLM models (like Claude 3 or GPT-4) and fine-tuning strategies to improve accuracy for your specific use case.