chainstream-graphql
# 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**: `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 25 cubes |
## 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](https://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
| 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)
```bash
npx @chainstream-io/cli graphql schema --summary
```
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:
```bash
npx @chainstream-io/cli graphql schema --type DEXTrades
```
### Step 2: Construct and Execute Query
**MANDATORY — READ** [references/schema-guide.md](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](../shared/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 {
OHLC(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, 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 `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" | No API Key configured | `npx @chainstream-io/cli config set --key apiKey --value <key>` |
| 402 | No active subscription | CLI auto-handles: plan selection → x402/MPP payment → retry. **MANDATORY — READ** [`shared/x402-payment.md`](../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: ask the user "Do you have a ChainStream API Key?" — if yes, set it; if no, load [`shared/x402-payment.md`](../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](references/schema-guide.md) | Query syntax, filter operators, joinXxx rules, advanced patterns, common mistakes | Before constructing any query |
| [query-patterns.md](references/query-patterns.md) | 20+ ready-to-use query templates by scenario | When building queries for common use cases |
| [x402-payment.md](../shared/x402-payment.md) | x402 and MPP payment protocols, plan purchase flow | On 402 errors or when user needs subscription |
| [authentication.md](../shared/authentication.md) | API Key setup, wallet auth, MCP config | On auth errors |
## Related Skills
- [chainstream-data](../chainstream-data/) — Standard REST/MCP queries for common analytics (token search, market trending, wallet profile). Use when pre-built endpoints suffice.
- [chainstream-defi](../chainstream-defi/) — DeFi execution: swap, bridge, create token, sign transactions. Use when analysis leads to action.
标签
skill
ai
