chainstream-graphql

---
name: chainstream-graphql
description: >-
license: MIT
---

# 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:**
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`](../shared/authentication.md#agent-bootstrap-checklist).

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](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 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](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 {
    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`](../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:
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`](../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](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.