ChainStream GraphQL

Flexible GraphQL interface to ChainStream's on-chain data warehouse. 25 cubes organized in 3 chain groups (EVM / Solana / Trading), covering DEX trades, token-centric trade analysis, OHLC, wallet PnL, transfers, blocks, transactions, prediction markets, and more — across Solana, Ethereum, BSC, and Polygon.

- Endpoint: https://graphql.chainstream.io/graphql (routed through APISIX gateway)
CLI: INLINECODE1
Auth: API Key via X-API-KEY header
Payment: x402 (USDC on Base/Solana) or MPP (USDC.e on Tempo) — auto-handled by CLI

When to Use GraphQL vs chainstream-data

Scenario	Use	Why
Standard token search, market trending, wallet profile	INLINECODE3 (REST/MCP)	Pre-built endpoints, simpler
Cross-cube JOIN (trades + instructions, trades + transfers)

Integration Path

1. Has API Key?

→ YES → Use CLI directly: npx @chainstream-io/cli graphql query --query '...' → NO → CLI auto-handles on first 402 (see Payment section below)

2. First time / unsure about schema?

→ Run npx @chainstream-io/cli graphql schema --summary to discover available cubes → Run npx @chainstream-io/cli graphql schema --type DEXTrades to drill into a specific cube

3. Need full schema reference for complex query construction?

→ Run npx @chainstream-io/cli graphql schema --full for complete field list + rules

Getting an API Key

GraphQL goes through ChainStream's unified APISIX gateway — same API Key and subscription quota as the REST API.

- Dashboard users: app.chainstream.io → API Keys
AI Agents (x402): CLI auto-purchases on first 402 — USDC on Base or Solana → API Key auto-saved to INLINECODE9
AI Agents (MPP): tempo request "https://api.chainstream.io/mpp/purchase?plan=<PLAN>" → API Key auto-returned
CLI auto-payment: No pre-purchase needed. First graphql query that triggers 402 → interactive plan selection → payment → auto-retry

CODEBLOCK0

Endpoint Selector

Intent	CLI Command
List all cubes + descriptions	INLINECODE12
Explore one cube's fields

npx @chainstream-io/cli graphql schema --type <CubeName> | | Full schema reference | npx @chainstream-io/cli graphql schema --full | | Force-refresh cached schema | npx @chainstream-io/cli graphql schema --summary --refresh | | Execute inline query | npx @chainstream-io/cli graphql query --query '<graphql>' | | Execute query from file | npx @chainstream-io/cli graphql query --file ./query.graphql | | Execute with variables | npx @chainstream-io/cli graphql query --query '...' --var '{"key":"value"}' | | Machine-readable output | Append --json to any command |

AI Workflow

Step 1: Discover Schema (first time or when unsure)

CODEBLOCK1

This returns a compact list of all 25 cubes organized by chain group (EVM/Solana/Trading) with descriptions and top-level fields. If you need details on a specific cube:

CODEBLOCK2

Step 2: Construct and Execute Query

MANDATORY — READ references/schema-guide.md before constructing your first query.

Based on schema knowledge + user intent, construct a GraphQL query and execute:

CODEBLOCK3

If the user has no subscription, use the non-interactive purchase flow: plan status --json → wallet pricing --json (present plans to user) → plan purchase --plan <USER_CHOSEN> --json (signs x402 payment, returns API Key). See x402-payment.md for details.

Step 3: Analyze Results

- Parse JSON output
Identify data patterns (time series, ranking, distribution, comparison)
Provide insights in natural language
If visualization is needed, choose appropriate chart type based on data shape

Query Construction Quick Reference

The schema uses chain group wrappers as the top-level entry point:

CODEBLOCK4

- Chain group wrapper: Top-level required. Solana, EVM(network: ...), or Trading.
network: Only on EVM wrapper. Values: eth, bsc, polygon.
limit: {count: N, offset: M}. Default 25.
orderBy: {descending: Field} or {ascending: Field}. For computed fields: {descendingByField: "field_name"}.
where: {Group: {Field: {operator: value}}}. OR conditions: any: [{...}, {...}].
DateTime format: "YYYY-MM-DD HH:MM:SS" — NO T, NO Z. Critical for ClickHouse.
DateTimeFilter: since, till, after, before — NEVER gt/lt.
joinXxx: LEFT JOIN to related cubes. Always prefer over multiple queries.
dataset: Optional wrapper arg — realtime, archive, or combined (default).
aggregates: Optional wrapper arg — yes, no, or only.

Chain Groups and Cubes

Chain Group	Wrapper	Cubes
Solana	INLINECODE51	DEXTrades, DEXTradeByTokens, Transfers, BalanceUpdates, DEXPoolEvents, TokenSupplyUpdates, Blocks, Transactions, Instructions, Rewards, DEXOrders, DEXPools, TokenHolders, TransactionBalances, WalletTokenPnl
EVM

EVM(network: eth\|bsc\|polygon) { ... } | DEXTrades, DEXTradeByTokens, Transfers, BalanceUpdates, DEXPoolEvents, TokenSupplyUpdates, Blocks, Transactions, Events, Calls, MinerRewards, DEXPools, TokenHolders, DEXPoolSlippages, TransactionBalances, Uncles, WalletTokenPnl, PredictionTrades, PredictionManagements, PredictionSettlements* | | Trading | Trading { ... } | OHLC, TokenTradeStats |

*Prediction cubes only available on polygon network.

NEVER Do

- NEVER use flat query format (CubeName(network: sol) without chain group wrapper) — always wrap in Solana { ... }, EVM(network: ...) { ... }, or INLINECODE58
NEVER guess field names without checking schema first — run graphql schema --summary or INLINECODE60
NEVER use ISO 8601 datetime format (2026-03-31T00:00:00Z) — ClickHouse requires INLINECODE62
NEVER use gt/lt on DateTime fields — use since/after/before/INLINECODE68
NEVER split related data into multiple queries when joinXxx can combine them
NEVER auto-select a payment plan — always let the user choose

Error Recovery

Error	Meaning	Recovery
401 / "Not authenticated"	No API Key configured	INLINECODE69
402

On 401/402: ask the user "Do you have a ChainStream API Key?" — if yes, set it; if no, load shared/x402-payment.md for the full purchase flow. GraphQL shares the same API Key / subscription pool as the REST API — no separate purchase needed.

Skill Map

Reference	Content	When to Load
schema-guide.md	Query syntax, filter operators, joinXxx rules, advanced patterns, common mistakes	Before constructing any query
query-patterns.md

Related Skills

- chainstream-data — Standard REST/MCP queries for common analytics (token search, market trending, wallet profile). Use when pre-built endpoints suffice.
chainstream-defi — DeFi execution: swap, bridge, create token, sign transactions. Use when analysis leads to action.

ChainStream GraphQL

ChainStream链上数据仓库的灵活GraphQL接口。25个数据立方体分布在3个链组（EVM/Solana/交易）中，覆盖DEX交易、代币中心化交易分析、OHLC、钱包盈亏、转账、区块、交易、预测市场等——横跨Solana、Ethereum、BSC和Polygon。

- 端点: https://graphql.chainstream.io/graphql（通过APISIX网关路由）
CLI: npx @chainstream-io/cli graphql
认证: 通过X-API-KEY头传递API密钥
支付: x402（Base或Solana上的USDC）或MPP（Tempo上的USDC.e）——CLI自动处理

何时使用GraphQL vs chainstream-data

场景	使用	原因
标准代币搜索、市场趋势、钱包画像	chainstream-data（REST/MCP）	预构建端点，更简单
跨立方体JOIN（交易+指令，交易+转账）

集成路径

1. 已有API密钥？

→ 是 → 直接使用CLI：npx @chainstream-io/cli graphql query --query ... → 否 → CLI在首次402时自动处理（见下方支付部分）

2. 首次使用/不确定模式？

→ 运行 npx @chainstream-io/cli graphql schema --summary 查看可用立方体 → 运行 npx @chainstream-io/cli graphql schema --type DEXTrades 深入查看特定立方体

3. 需要完整模式参考以构建复杂查询？

→ 运行 npx @chainstream-io/cli graphql schema --full 获取完整字段列表+规则

获取API密钥

GraphQL通过ChainStream的统一APISIX网关——与REST API使用相同的API密钥和订阅配额。

- 仪表盘用户: app.chainstream.io → API密钥
AI代理（x402）: CLI在首次402时自动购买——Base或Solana上的USDC → API密钥自动保存至~/.config/chainstream/config.json
AI代理（MPP）: tempo request https://api.chainstream.io/mpp/purchase?plan= → API密钥自动返回
CLI自动支付: 无需预先购买。首次触发402的graphql query → 交互式方案选择 → 支付 → 自动重试

bash

选项A：设置现有API密钥

npx @chainstream-io/cli config set --key apiKey --value

选项B：创建钱包用于x402自动支付

npx @chainstream-io/cli login

选项C：先查看定价

npx @chainstream-io/cli wallet pricing

端点选择器

意图	CLI命令
列出所有立方体+描述	npx @chainstream-io/cli graphql schema --summary
探索一个立方体的字段

npx @chainstream-io/cli graphql schema --type | | 完整模式参考 | npx @chainstream-io/cli graphql schema --full | | 强制刷新缓存的模式 | npx @chainstream-io/cli graphql schema --summary --refresh | | 执行内联查询 | npx @chainstream-io/cli graphql query --query | | 从文件执行查询 | npx @chainstream-io/cli graphql query --file ./query.graphql | | 带变量执行查询 | npx @chainstream-io/cli graphql query --query ... --var {key:value} | | 机器可读输出 | 在任何命令后追加 --json |

AI工作流

步骤1：发现模式（首次或不确定时）

bash
npx @chainstream-io/cli graphql schema --summary

这将返回按链组（EVM/Solana/交易）组织的全部25个立方体的紧凑列表，包含描述和顶级字段。如需了解特定立方体的详细信息：

bash
npx @chainstream-io/cli graphql schema --type DEXTrades

步骤2：构建并执行查询

必须——阅读 references/schema-guide.md 后再构建第一个查询。

基于模式知识和用户意图，构建GraphQL查询并执行：

bash
npx @chainstream-io/cli graphql query --query query {
Solana {
DEXTrades(limit: {count: 25}, orderBy: {descending: Block_Time}) {
Block { Time }
Trade { Buy { Currency { MintAddress } Amount PriceInUSD } Sell { Currency { MintAddress } Amount } Dex { ProtocolName } }
}
}
} --json

如果用户没有订阅，使用非交互式购买流程：plan status --json → wallet pricing --json（向用户展示方案）→ plan purchase --plan <用户选择的> --json（签署x402支付，返回API密钥）。详见 x402-payment.md。

步骤3：分析结果

- 解析JSON输出
识别数据模式（时间序列、排名、分布、比较）
用自然语言提供见解
如需可视化，根据数据形状选择合适的图表类型

查询构建快速参考

模式使用链组包装器作为顶级入口点：

graphql

Solana（无需网络参数）

query {
Solana {
CubeName(limit: {count: N}, orderBy: {descending: Field}, where: {...}) {
FieldGroup { SubField }
joinXxx { ... }
count
}
}
}

EVM（需要网络参数：eth | bsc | polygon）

query { EVM(network: eth) { CubeName(limit: {count: N}, orderBy: {descending: Field}, where: {...}) { FieldGroup { SubField } } } }

交易（跨链预聚合，无需网络参数）

query { Trading { OHLC(tokenAddress: {is: ...}, limit: {count: 24}) { TimeMinute Price { Open High Low Close } } } }

- 链组包装器: 顶级必需。Solana、EVM(network: ...)或Trading。
network: 仅用于EVM包装器。值：eth、bsc、polygon。
limit: {count: N, offset: M}。默认25。
orderBy: {descending: Field}或{ascending: Field}。对于计算字段：{descendingByField: field_name}。
where: {Group: {Field: {operator: value}}}。OR条件：any: [{...}, {...}]。
DateTime格式: YYYY-MM-DD HH:MM:SS——不要T，不要Z。对ClickHouse至关重要。
DateTimeFilter: since、till、after、before——绝对不要用gt/lt。
joinXxx: 与相关立方体的LEFT JOIN。始终优于多次查询。
dataset: 可选的包装器参数——realtime、archive或combined（默认）。
aggregates: 可选的包装器参数——yes、no或only。

链组和立方体

链组	包装器	立方体
Solana	Solana { ... }	DEXTrades、DEXTradeByTokens、Transfers、BalanceUpdates、DEXPoolEvents、TokenSupplyUpdates、Blocks、Transactions、Instructions、Rewards、DEXOrders、DEXPools、TokenHolders、TransactionBalances、WalletTokenPnl
EVM

EVM(net

chainstream-graphql链流图查询