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

> Build an assistant that turns plain-language questions about tokens and wallets into safe database queries, runs them, and explains the results. Step by step, with TypeScript.

- Author: OnChain Team
- Published: 2026-10-31
- Page: https://www.onchain.ro/blog/ai-assistant-on-chain-data

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

```diagram
title: The model plans and explains; your code decides what runs
node user at 0,1 user "User" "Plain-language question"
node plan at 1,1 ai "Planner" "Returns a typed QuerySpec"
node compile at 2,1 default "Validate + compile" "Allow-listed fields only"
node reject at 2,2.1 warn "Rejected" "Out of scope or invalid"
node db at 3,1 store "MongoDB" "Read-only user, 5 s limit"
node explain at 4,0.4 ai "Explainer" "Answers only from rows"
node chart at 4,1.6 default "Chart" "Drawn from the rows"
node ui at 5,1 user "Chat UI" "Streamed answer and chart"
edge user -> plan "question"
edge plan -> compile "QuerySpec"
edge compile -> reject "invalid" fail
edge compile -> db "pipeline"
edge db -> explain "rows"
edge db -> chart "rows"
edge explain -> ui "text stream"
edge chart -> ui
```

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](/blog/solana-real-time-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.

```ts
// spec.ts
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](https://platform.claude.com/docs/en/build-with-claude/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.

```ts
// plan.ts
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.

```ts
// compile.ts
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.

```ts
// execute.ts
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.

```ts
// explain.ts
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

```ts
// assistant.ts
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](/services/ai-chatbots-solana-data) work.

---

OnChain · 15 Bld. Iuliu Maniu, 061075 Bucharest, Romania · contact@onchain.ro · https://www.onchain.ro
