ChainStream GraphQL#

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

• Endpoint: https://graphql.chainstream.io/graphql (routed through APISIX gateway)
• CLI: npx @chainstream-io/cli graphql
• 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#

ScenarioUseWhyStandard token search, market trending, wallet profilechainstream-data (REST/MCP)Pre-built endpoints, simplerCross-cube JOIN (trades + instructions, trades + transfers)GraphQLjoinXxx supportCustom aggregation (count, sum, avg with groupBy)GraphQLMetrics + dimension groupingComplex filters (multi-condition WHERE, nested, OR via any)GraphQLFull filter operator supportTime-series data with custom resolutionGraphQLTime interval bucketing + dimension aggregationPrediction market data (PolyMarket)GraphQLPredictionTrades/Managements/Settlements cubes (Polygon)Data not exposed by REST APIGraphQLDirect access to all 27 cubes

Integration Path#

Before anything else (CLI path), ensure user is authenticated:

1. npx @chainstream-io/cli config auth — check login status
2. If NOT logged in → npx @chainstream-io/cli login (creates EVM + Solana wallet, auto-grants nano trial plan: 50K CU free, 30 days — no purchase needed)
3. npx @chainstream-io/cli plan status — verify subscription is active

New users get a free trial on login (50K CU). For details on trial plans and upgrade options, see shared/authentication.md.

1. Has API Key? → YES → Use CLI directly: npx @chainstream-io/cli graphql query --query '...' → NO → Ensure logged in (see above), then CLI auto-handles on first 402

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 ~/.config/chainstream/config.json
• 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

bash

# Option A: Set existing API Key
npx @chainstream-io/cli config set --key apiKey --value <your-api-key>

# Option B: Create wallet for x402 auto-payment
npx @chainstream-io/cli login

# Option C: Check pricing first
npx @chainstream-io/cli wallet pricing

Endpoint Selector#

IntentCLI CommandList all cubes + descriptionsnpx @chainstream-io/cli graphql schema --summaryExplore one cube's fieldsnpx @chainstream-io/cli graphql schema --type <CubeName>Full schema referencenpx @chainstream-io/cli graphql schema --fullForce-refresh cached schemanpx @chainstream-io/cli graphql schema --summary --refreshExecute inline querynpx @chainstream-io/cli graphql query --query '<graphql>'Execute query from filenpx @chainstream-io/cli graphql query --file ./query.graphqlExecute with variablesnpx @chainstream-io/cli graphql query --query '...' --var '{"key":"value"}'Machine-readable outputAppend --json to any command

AI Workflow#

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

bash

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

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

bash

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

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:

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

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:

graphql

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

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

# Trading (cross-chain pre-aggregated, no network arg)
query {
  Trading {
    Pairs(tokenAddress: {is: "..."}, limit: {count: 24}) {
      TimeMinute
      Price { Open High Low Close }
    }
  }
}

• 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 GroupWrapperCubesSolanaSolana { ... }DEXTrades, DEXTradeByTokens, Transfers, BalanceUpdates, Blocks, Transactions, DEXPools, Instructions, InstructionBalanceUpdates, Rewards, DEXOrders, TokenSupplyUpdatesEVMEVM(network: eth|bsc|polygon) { ... }DEXTrades, DEXTradeByTokens, Transfers, BalanceUpdates, Blocks, Transactions, DEXPoolEvents, Events, Calls, MinerRewards, DEXPoolSlippages, TokenHolders, TransactionBalances, Uncles, PredictionTrades*, PredictionManagements*, PredictionSettlements*TradingTrading { ... }Pairs, Tokens, Currencies, Trades

*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 Trading { ... }
• NEVER guess field names without checking schema first — run graphql schema --summary or --type
• NEVER use ISO 8601 datetime format ( 2026-03-31T00:00:00Z) — ClickHouse requires "2026-03-31 00:00:00"
• NEVER use gt/ lt on DateTime fields — use since/ after/ before/ till
• 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#

ErrorMeaningRecovery401 / "Not authenticated"Not logged in or no API KeyFirst config auth → login if not logged in (auto-grants nano trial 50K CU) → retry. If still failing: config set --key apiKey --value <key>402No active subscriptionFirst config auth → login if needed (trial may suffice) → plan status. If no subscription or quota exhausted: wallet pricing then plan purchase. MANDATORY — READshared/x402-payment.md for manual purchase flow"GraphQL error: ..."Invalid query syntax or non-existent fieldCheck field names against graphql schema --type <cube>429Rate limitWait 1s, exponential backoff5xxServer errorRetry once after 2s

On 401/402, follow this sequence:

1. Check login: npx @chainstream-io/cli config auth — if not logged in, run login (creates wallet + auto-grants nano trial with 50K CU free). After login, retry the failed command — it will likely succeed now
2. Check subscription: npx @chainstream-io/cli plan status — if active: true with remaining quota, retry
3. If logged in but no subscription: ask the user "Do you have a ChainStream API Key?" — if yes, config set --key apiKey --value <key> and retry; if no, load shared/x402-payment.md for the purchase flow. GraphQL shares the same API Key / subscription pool as the REST API — no separate purchase needed.

Skill Map#

ReferenceContentWhen to Loadschema-guide.mdQuery syntax, filter operators, joinXxx rules, advanced patterns, common mistakesBefore constructing any queryquery-patterns.md20+ ready-to-use query templates by scenarioWhen building queries for common use casesx402-payment.mdx402 and MPP payment protocols, plan purchase flowOn 402 errors or when user needs subscriptionauthentication.mdAPI Key setup, wallet auth, MCP configOn auth errors

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.