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

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=\x3CPLAN>" → API Key auto-returned
• CLI auto-payment: No pre-purchase needed. First graphql query that triggers 402 → interactive plan selection → payment → auto-retry

# Option A: Set existing API Key
npx @chainstream-io/cli config set --key apiKey --value \x3Cyour-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

AI Workflow

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

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:

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:

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 \x3CUSER_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:

# 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

*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

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 \x3Ckey> 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

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.