Prompt Guidance

The way you phrase queries during the Closed Beta has a direct impact on the accuracy and usefulness of GraphEngine responses. Because the platform is still evolving, structured and precise inputs will yield the best results. This guide outlines the best practices for querying subgraphs and highlights common pitfalls to avoid.

DISCLAIMER: UNDERSTAND RESPONSE TIMES

Subgraph queries typically take around 30 seconds to resolve. This is normal for a system pulling, indexing, and reasoning over live blockchain data. Please allow for this delay before re-running queries.

Best Practise (Do's)

Align with the Subgraph Scheme

Each subgraph is defined by a schema that outlines the entities, fields, and event types it contains. Always review the schema and description before querying. If you ask for data outside the scope of the schema, results will either be empty or inaccurate.

Use Precise Entities and Directions

Be clear about what you want. Instead of asking broad questions like “Show me swaps,” specify which swaps and under what conditions. Use exact domain terms such as “Transfer,” “Swap,” “Position,” “Pool,” or “Wallet.” Distinguish between directions (e.g., “tokens sent by Wallet A” vs. “tokens received by Wallet A”). This precision helps the query model interpret intent correctly.

Provide Exact Identifiers

When possible, use full addresses for tokens and wallets (e.g., 0x123...). Token symbols (e.g., “GAI”) can be used, but addresses reduce ambiguity and errors. Over time, external integrations will improve symbol and alias recognition, but for now addresses remain the most reliable option.

Keep Queries Focused

Each query should address one specific question. Complex, multi-part queries are harder to resolve and may fail to return results. Breaking down a broad research task into smaller, focused queries will produce faster and more accurate outputs.

Specify Sorting and Metrics

If you care about order or scale, say so. For example, “largest transfer by amount,” “most recent swap,” or “highest number of transactions.” Providing these parameters avoids guesswork and ensures results are relevant to your intent.

Common Mistakes (Dont's)

Avoid Vague or Unbounded Requests

Overly broad queries such as “Show me all transactions ever” are impractical and resource-intensive. The system is designed for specific, actionable insights, not unbounded data dumps.

Don’t Query Out-of-Schema Concepts

If the subgraph does not index certain event types (e.g., approvals, token burns, or NFT metadata), do not ask for them. Similarly, avoid off-chain data requests (e.g., “price in USD”) unless the subgraph explicitly supports those feeds.

Avoid Ambiguous Context

Phrases like “across all chains” or “all tokens” are too broad. Always reference the specific chain or token of interest, ideally with an address. ENS names are not currently supported and should be avoided.

Limit Multi-Part Joins

Queries that combine multiple unrelated conditions (e.g., “show swaps from Wallet A AND positions in Pool B AND transfers from Token C”) should be split into separate queries. Simpler structures are not only faster but also more reliable.

Why This Matters

GraphEngine’s Closed Beta is an important phase for refining both the indexing stack and the AI query model. Following these guidelines ensures your experience is productive and your feedback is actionable. As the system matures with better contextual learning, external API integrations, and schema expansions, natural language inputs will become more flexible. For now, clarity and precision are key to achieving the best outcomes.