Skip to content
ON CHAIN
Menu

How to Build an AI Assistant That Answers Questions From On-Chain Data

Language models are bad at remembering blockchain data and good at writing queries. This guide builds an assistant that plans a query, validates it, runs it read-only and explains the answer.

By OnChain Team8 min read

An AI assistant for on-chain data should not answer from the model's memory. It should turn the user's question into a structured query plan, check that plan against a fixed list of allowed collections and fields, compile it into a real database query, run it with a read-only user and a timeout, and then ask the model to explain the rows it got back. The model does the language work; your code keeps control of what runs against your data. This guide builds that loop in TypeScript with the Claude API and MongoDB.

The design in one picture

The model plans and explains; your code decides what runs
USERUserPlain-languagequestionAI MODELPlannerReturns a typedQuerySpecValidate + compileAllow-listed fieldsonlyFAILURE PATHRejectedOut of scope orinvalidDATAMongoDBRead-only user, 5 slimitAI MODELExplainerAnswers only fromrowsChartDrawn from the rowsUSERChat UIStreamed answer andchartquestionQuerySpecinvalidpipelinerowsrowstext stream

Main flowFailure pathSwipe to see the whole diagram →

The key decision is that the model never writes raw database queries. It fills in a small, typed plan that your code compiles. That removes a whole class of problems: queries that scan everything, touch collections they should not, or write data.

Step 1: Index the data you want to ask about

The assistant is only as good as the data under it. For token and wallet questions, two collections cover a lot:

Collection One document per Useful fields
swaps Decoded swap mint, wallet, side ("buy"/"sell"), amount, amountUsd, ts
holders Wallet and token, daily snapshot mint, wallet, balance, day

Building those collections is a data pipeline problem, covered in how to build a real-time Solana data pipeline. Add indexes for the filters you expect, at least { mint: 1, ts: -1 } on swaps and { mint: 1, day: -1 } on holders.

Step 2: Define the query plan schema

The plan is the contract between the model and your code. Keep it small. Every field the model can choose is an enum, so it cannot invent names.

spec.tsTypeScript
import { z } from "zod";

export const FIELDS = {
  swaps: ["mint", "wallet", "side", "amount", "amountUsd", "ts"],
  holders: ["mint", "wallet", "balance", "day"],
} as const;

export const QuerySpec = z.object({
  collection: z.enum(["swaps", "holders"]),
  filters: z.array(
    z.object({
      field: z.enum(["mint", "wallet", "side"]),
      value: z.string(),
    }),
  ),
  sinceDays: z.number().int().nullable(), // time window, null for "all time"
  groupBy: z.enum(["wallet", "mint", "day"]).nullable(),
  metric: z.enum(["count", "sumAmount", "sumAmountUsd", "maxBalance"]),
  order: z.enum(["desc", "asc"]),
  limit: z.number().int(),
});

export type QuerySpec = z.infer<typeof QuerySpec>;

Notice what is missing: no free-text field names, no operators beyond equality, no way to express a write. If users need more, add it deliberately, one option at a time.

Step 3: Ask the model for a plan

Claude's structured outputs constrain the response to your schema, and the SDK validates it with Zod. Describe the data in the system prompt, including what each field means, because the model cannot see your database.

plan.tsTypeScript
import Anthropic from "@anthropic-ai/sdk";
import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod";
import { QuerySpec } from "./spec";

const client = new Anthropic(); // reads ANTHROPIC_API_KEY

const SYSTEM = `You turn questions about Solana tokens and wallets into a query plan.
Data available:
- swaps: one row per swap. mint = token address, wallet = trader, side = "buy" | "sell",
  amount = tokens, amountUsd = USD value at trade time, ts = trade time.
- holders: one row per wallet per token per day. balance = tokens held at end of day.
Rules:
- Use the token address the user gives; never guess an address.
- "Top", "largest" and "most" mean order "desc".
- Use limit 10 unless the user asks for a number. Never exceed 50.
- If the question cannot be answered from this data, return metric "count" with no filters
  and a limit of 1; the explain step will tell the user it is out of scope.`;

export async function plan(question: string) {
  const response = await client.messages.parse({
    model: "claude-opus-5-5",
    max_tokens: 2000,
    system: SYSTEM,
    messages: [{ role: "user", content: question }],
    output_config: { format: zodOutputFormat(QuerySpec) },
  });

  if (response.stop_reason === "refusal")
    throw new Error("The model declined this question");
  if (!response.parsed_output) throw new Error("No valid plan returned");
  return response.parsed_output;
}

Step 4: Validate and compile the plan

Never trust the plan just because it matches the schema. Clamp the limit, check that filters make sense for the collection, and only then build the pipeline.

compile.tsTypeScript
import type { Document } from "mongodb";
import { FIELDS, type QuerySpec } from "./spec";

const DAY = 24 * 60 * 60 * 1000;

export function compile(spec: QuerySpec): { collection: string; pipeline: Document[] } {
  const allowed: readonly string[] = FIELDS[spec.collection];
  const match: Record<string, unknown> = {};

  for (const f of spec.filters) {
    if (!allowed.includes(f.field))
      throw new Error(`Field ${f.field} is not in ${spec.collection}`);
    match[f.field] = f.value;
  }
  if (spec.sinceDays !== null) {
    const timeField = spec.collection === "swaps" ? "ts" : "day";
    match[timeField] = {
      $gte: new Date(Date.now() - Math.min(spec.sinceDays, 365) * DAY),
    };
  }

  const value = {
    count: { $sum: 1 },
    sumAmount: { $sum: "$amount" },
    sumAmountUsd: { $sum: "$amountUsd" },
    maxBalance: { $max: "$balance" },
  }[spec.metric];

  const groupKey =
    spec.groupBy === "day"
      ? {
          $dateTrunc: {
            date: spec.collection === "swaps" ? "$ts" : "$day",
            unit: "day",
          },
        }
      : spec.groupBy
        ? `${spec.groupBy}`
        : null;

  return {
    collection: spec.collection,
    pipeline: [
      { $match: match },
      { $group: { _id: groupKey, value } },
      { $sort: { value: spec.order === "desc" ? -1 : 1 } },
      { $limit: Math.max(1, Math.min(spec.limit, 50)) },
    ],
  };
}

Step 5: Execute with guardrails

Run the pipeline as a database user that can only read these collections, with a server-side time limit. These limits protect you even if the compiler has a bug.

execute.tsTypeScript
import { MongoClient, type Document } from "mongodb";

// a user with the read role only
const mongo = new MongoClient(process.env.MONGO_READONLY_URI!);
const db = mongo.db("chain");

export async function execute(collection: string, pipeline: Document[]) {
  return db
    .collection(collection)
    .aggregate(pipeline, { maxTimeMS: 5000, allowDiskUse: false })
    .toArray();
}

Create the user with only the built-in read role on this database. Log every plan, pipeline and row count, so you can see what users ask and where the planner struggles.

Step 6: Explain the results, streamed

Send the question, the plan and the rows back to the model and ask for a short, factual answer. Streaming makes the assistant feel fast even when the explanation takes a few seconds.

explain.tsTypeScript
import Anthropic from "@anthropic-ai/sdk";
import type { QuerySpec } from "./spec";

const client = new Anthropic();

export async function explain(
  question: string,
  spec: QuerySpec,
  rows: unknown[],
  write: (t: string) => void,
) {
  const stream = client.messages.stream({
    model: "claude-opus-5-5",
    max_tokens: 4000,
    system:
      "Answer the user's question using only the rows provided. " +
      "Quote numbers exactly as given. " +
      "If the rows do not answer the question, say so plainly. Two to four sentences. " +
      "Do not give investment advice.",
    messages: [
      {
        role: "user",
        content: [
          `Question: ${question}`,
          `Plan: ${JSON.stringify(spec)}`,
          `Rows: ${JSON.stringify(rows)}`,
        ].join("\n"),
      },
    ],
  });

  for await (const event of stream) {
    if (event.type === "content_block_delta" && event.delta.type === "text_delta")
      write(event.delta.text);
  }
  const final = await stream.finalMessage();
  if (final.stop_reason === "refusal")
    write("\n[The model declined to answer this question.]");
}

Step 7: Put it together

assistant.tsTypeScript
import { plan } from "./plan";
import { compile } from "./compile";
import { execute } from "./execute";
import { explain } from "./explain";

export async function ask(question: string, write: (t: string) => void) {
  const spec = await plan(question);
  const { collection, pipeline } = compile(spec);
  const rows = await execute(collection, pipeline);
  await explain(question, spec, rows, write);
  return { spec, rows }; // return the rows too, so the UI can draw a chart from real data
}

// Example
await ask("Which wallets bought the most of <token address> in the last 7 days?", (t) =>
  process.stdout.write(t),
);

Return the rows to the front end as well as the text. Draw the chart from the rows, never from numbers the model wrote, so the picture always matches the data.

Step 8: Test it like any other feature

Keep a list of 30 to 50 real questions with the plan you expect for each. Run it whenever you change the prompt, the schema or the model, and track how many plans match. Include questions the assistant should refuse, such as price predictions or data you do not have, and check that it says so instead of guessing.

For production, also consider:

  • Fallbacks. Handle stop_reason: "refusal", as above, and enable the API's server-side fallback option so a declined request can be retried on another model.
  • Caching. The system prompt is identical on every request, so prompt caching cuts cost and latency.
  • Rate limits per user. Every question costs two model calls and a query.

What we would do

Keep the planner's vocabulary small at launch and grow it from the questions users actually ask, which your logs will show. Most of the quality comes from the data model and the field descriptions in the system prompt, not from prompt tricks. Never let numbers in the answer come from anywhere but the query result.

This is the kind of system we build in our AI chatbots for blockchain data work.

Contact

Need this built for your product?

Tell us what you are building and where you are stuck. Email is the fastest way to reach the team.

contact@onchain.ro