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

| Scenario | Use | Why | |----------|-----|-----| | Standard token search, market trending, wallet profile | chainstream-data (REST/MCP) | Pre-built endpoints, simpler | | Cross-cube JOIN (trades + instructions, trades + transfers) | GraphQL | joinXxx support | | Custom aggregation (count, sum, avg with groupBy) | GraphQL | Metrics + dimension grouping | | Complex filters (multi-condition WHERE, nested, OR via any) | GraphQL | Full filter operator support | | Time-series data with custom resolution | GraphQL | Time interval bucketing + dimension aggregation | | Prediction market data (PolyMarket) | GraphQL | PredictionTrades/Managements/Settlements cubes (Polygon) | | Data not exposed by REST API | GraphQL | Direct access to all 27 cubes |

Integration Path

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

npx @chainstream-io/cli config auth — check login status
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)
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.

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

# 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

| Intent | CLI Command | |--------|-------------| | List all cubes + descriptions | npx @chainstream-io/cli graphql schema --summary | | 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)

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

# 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 Group | Wrapper | Cubes | |------------|---------|-------| | Solana | Solana { ... } | DEXTrades, DEXTradeByTokens, Transfers, BalanceUpdates, Blocks, Transactions, DEXPools, Instructions, InstructionBalanceUpdates, Rewards, DEXOrders, TokenSupplyUpdates | | EVM | EVM(network: eth\|bsc\|polygon) { ... } | DEXTrades, DEXTradeByTokens, Transfers, BalanceUpdates, Blocks, Transactions, DEXPoolEvents, Events, Calls, MinerRewards, DEXPoolSlippages, TokenHolders, TransactionBalances, Uncles, PredictionTrades*, PredictionManagements*, PredictionSettlements* | | Trading | Trading { ... } | 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

| Error | Meaning | Recovery | |-------|---------|----------| | 401 / "Not authenticated" | Not logged in or no API Key | First config auth → login if not logged in (auto-grants nano trial 50K CU) → retry. If still failing: config set --key apiKey --value <key> | | 402 | No active subscription | First config auth → login if needed (trial may suffice) → plan status. If no subscription or quota exhausted: wallet pricing then plan purchase. MANDATORY — READ shared/x402-payment.md for manual purchase flow | | "GraphQL error: ..." | Invalid query syntax or non-existent field | Check field names against graphql schema --type <cube> | | 429 | Rate limit | Wait 1s, exponential backoff | | 5xx | Server error | Retry once after 2s |

On 401/402, follow this sequence:

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
Check subscription: npx @chainstream-io/cli plan status — if active: true with remaining quota, retry
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

| 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 | 20+ ready-to-use query templates by scenario | When building queries for common use cases | | x402-payment.md | x402 and MPP payment protocols, plan purchase flow | On 402 errors or when user needs subscription | | authentication.md | API Key setup, wallet auth, MCP config | On 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.