Skip to main content

​
Overview

The chainstream-graphql skill gives AI agents flexible SQL-like access to ChainStream’s on-chain data warehouse through GraphQL. It is the right tool whenever a pre-built REST/MCP endpoint is not expressive enough — cross-cube JOINs, custom aggregations, multi-condition filters, custom time-series resolution, or data only exposed via GraphQL (e.g. PolyMarket prediction cubes).
  • Pattern: Tool (read-only, no signing)
  • Endpoint: https://graphql.chainstream.io/graphql (routed through APISIX)
  • CLI: npx @chainstream-io/cli graphql
  • Auth: API Key via X-API-KEY, or SIWX wallet token
  • Payment: Same API Key / subscription pool as REST (x402 / MPP auto-handled by CLI)
  • Scope: 27 cubes across 3 chain groups — Solana, EVM(network: eth | bsc | polygon), Trading

​
When to Use

Decision matrix vs chainstream-data:
ScenarioUseWhy
Standard token search, market trending, wallet profilechainstream-dataPre-built REST / MCP endpoints, simpler
Cross-cube JOIN (trades + transfers, pools + events)chainstream-graphqljoinXxx support
Custom aggregation (count / sum / avg with groupBy)chainstream-graphqlMetrics + dimension grouping
Multi-condition filters (nested, OR via any)chainstream-graphqlFull filter operator set
Time-series with custom resolution / bucketschainstream-graphqlTime interval bucketing
Prediction market data (PolyMarket on Polygon)chainstream-graphqlPredictionTrades / Managements / Settlements cubes

​
Integration Path

​
Channel Matrix

GraphQL is a single surface accessed from different callers:
OperationCLI CommandSDK Method
List all cubes (summary)graphql schema --summaryN/A — use CLI for discovery
Drill into one cubegraphql schema --type <CubeName>N/A
Full schema referencegraphql schema --fullN/A
Force-refresh cached schemagraphql schema --summary --refreshN/A
Inline querygraphql query --query '<gql>'client.graphql.query(gql)
Query from filegraphql query --file ./q.graphqlclient.graphql.query(fs.readFileSync(...))
Query with variablesgraphql query --query '...' --var '{"k":"v"}'client.graphql.query(gql, vars)
Machine-readable outputAppend --jsonNative JSON return

​
AI Workflows

​
Discover Schema

Always start here if the agent doesn’t already know which cube it needs. 
npx @chainstream-io/cli graphql schema --summary
npx @chainstream-io/cli graphql schema --type DEXTrades
--summary returns a compact catalog of all 27 cubes grouped by chain (EVM / Solana / Trading), with top-level fields and descriptions. --type expands one cube’s field tree for query construction.

​
Construct and Run a Query

The schema uses chain group wrappers as the top-level entry point. 
query {
  Solana {
    DEXTrades(
      limit: { count: 25 }
      orderBy: { descending: Block_Time }
    ) {
      Block { Time }
      Trade {
        Buy  { Currency { MintAddress } Amount PriceInUSD }
        Sell { Currency { MintAddress } Amount }
        Dex  { ProtocolName }
      }
    }
  }
}
Execute from the CLI: 
npx @chainstream-io/cli graphql query --file ./query.graphql --json
Or inline: 
npx @chainstream-io/cli graphql query \
  --query 'query { Solana { DEXTrades(limit:{count:5}) { Block { Time } } } }' \
  --json

​
Query Construction Quick Reference

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

​
Chain Groups and Cubes

Chain GroupWrapperCubes
SolanaSolana { ... }DEXTrades, DEXTradeByTokens, Transfers, BalanceUpdates, Blocks, Transactions, DEXPools, Instructions, InstructionBalanceUpdates, Rewards, DEXOrders, TokenSupplyUpdates
EVMEVM(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.

​
Safety Rules

These rules are enforced by the skill to keep queries correct and avoid wasted quota.
RuleReason
Never use a flat CubeName(network: sol) — always wrap in a chain groupServer rejects un-wrapped queries
Never guess field names — run graphql schema --type <cube> firstSaves a round-trip of “field does not exist” errors
Never use ISO-8601 "2026-03-31T00:00:00Z" — use "2026-03-31 00:00:00"ClickHouse DateTime format
Never use gt / lt on DateTime — use since / after / before / tillDateTime filters are named
Never split related data across multiple queries when joinXxx can combineOne paid request instead of many
Never auto-select a payment plan — always let the user chooseBilling consent

​
Error Recovery

ErrorRecovery
401 / “Not authenticated”config auth — if not logged in, run login (auto-grants the nano trial, 50K CU). Then retry.
402 / “Payment required”plan status; if no active subscription, wallet pricing → plan purchase --plan <choice>. See x402 payments.
GraphQL error: field X does not existRe-check the field against graphql schema --type <cube>.
429Wait 1s, exponential backoff.
5xxRetry once after 2s.

chainstream-data

Standard REST/MCP queries for token, market and wallet analytics

chainstream-defi

Execute trades after analysis — swap, create token

GraphQL access method

Endpoint reference, auth, schema overview

CLI `graphql` subcommand

chainstream graphql schema and query reference