Starter Queries

When a user opens a chat surface for the first time — before they have typed anything — you often need to show them a few interesting prompts to click. chaos.chat.starterQueries returns five short, onboarding-focused suggestions. Pass a walletAddress and the backend substitutes the user's top asset and protocol names into the question templates; call it without one and the backend returns a hardcoded discovery list that works for any first-time user.

Quick example

Call starterQueries() with no arguments for the discovery list, or pass a walletAddress to get personalized suggestions. Render each string as a clickable chip.

import { Chaos } from '@chaoslabs/ai-sdk';
 
const chaos = new Chaos({ apiKey: process.env.CHAOS_API_KEY! });
 
// Discovery list — first-time users, disconnected wallets
const discovery = await chaos.chat.starterQueries();
console.log(discovery.source); // 'discovery'
for (const q of discovery.queries) {
  console.log(q.text);
}
 
// Personalized — substitutes the user's top asset + protocol names
const personalized = await chaos.chat.starterQueries({
  walletAddress: '0xabc...',
});
console.log(personalized.source); // 'portfolio'
for (const q of personalized.queries) {
  console.log(q.text);
}
 

Passing a walletAddress

The walletAddress parameter is optional. The backend routes internally based on wallet state:

The output is deterministic — the same wallet state always produces the same five strings. If the backend cannot resolve the wallet (lookup error, no holdings, rate limit), it falls back to the discovery list rather than returning an error.

Response shape

The response is a small envelope your UI can render directly:

export type StarterQueriesSource = 'discovery' | 'portfolio';
 
export interface StarterQuery {
  text: string;
  pillar?: string;
  capabilityShowcased?: string;
}
 
export interface StarterQueriesResponse {
  queries: StarterQuery[];
  source: StarterQueriesSource;
  generatedAt?: string | null;
}
 
export interface StarterQueriesParams {
  walletAddress?: string;
}
 

Every response contains exactly five queries. Each query is an object with text (the prompt string to render on the chip) and optional metadata (pillar, capabilityShowcased) for analytics — the hardcoded path returns text only. source is diagnostic (tells you which branch fired); it does not change how you render. generatedAt is present on the future generator phase and omitted on the hardcoded path.

Rendering suggestion chips

The typical pattern: fetch on surface open, render each string as a clickable chip, and on click pipe the selected text into chaos.chat.responses.create().

import { Chaos } from '@chaoslabs/ai-sdk';
import type { StarterQuery } from '@chaoslabs/ai-sdk';
 
export async function loadStarterQueries(
  chaos: Chaos,
  walletAddress?: string,
): Promise<StarterQuery[]> {
  const { queries } = await chaos.chat.starterQueries(
    walletAddress ? { walletAddress } : {},
  );
  return queries;
}
 
// In your UI — render each query as a clickable chip that pipes the text
// straight into chaos.chat.responses.create():
//
//   suggestions.map((q) => (
//     <Chip key={q.text} onClick={() => sendMessage(q.text)}>
//       {q.text}
//     </Chip>
//   ))
 

Next steps

• Quick Start — Set up the SDK and send your first request.
• Wallet Configuration — Attach a wallet so personalized suggestions light up.
• Real-Time Streaming — Stream the response to a clicked chip back to the UI.
• Multi-Turn Conversations — Continue the thread after a user picks a suggestion.