Chainstream Graphql

Execute flexible GraphQL queries against ChainStream's on-chain data warehouse (22 cubes across Solana, Ethereum, BSC). Use when user needs custom analytics...

Security Scan

The skill's functionality (GraphQL queries + payments) is plausible, but the runtime instructions ask the agent to perform sensitive actions (create/import wallets, store API keys, run external installers via npx/curl|bash) and contain contradictory guidance about auto-purchases — these inconsistencies and supply-chain touches warrant caution.

Purpose & Capability

The name/description (GraphQL access to ChainStream cubes) matches the instructions: calling a GraphQL endpoint, exploring schema, and running queries. However the instructions also require wallet creation/import and payment flows (x402/MPP) and saving API keys to ~/.config/chainstream/config.json. Those additional capabilities are plausible for a paid on-chain data API, but they expand the trust boundary substantially (private keys, persistent config) and should be expected only if you intend to let the agent manage payments/wallets.

Instruction Scope

SKILL.md and referenced docs instruct the agent to run external commands (npx @chainstream-io/cli, tempo request, curl|bash installer in shared docs), create or import private keys via CLI, and persist API keys/keys to disk. It also contains contradictory guidance: some parts imply CLI will auto-purchase on first 402, while shared/x402-payment.md explicitly requires presenting plans and explicit user selection. The instructions therefore both broaden the agent's actions (wallet creation, signing payments, storing secrets) and leave important decisions underspecified/contradictory — increasing risk of unintended purchases or key exposure.

Install Mechanism

This is an instruction-only skill (no install spec), but runtime relies on npx to fetch @chainstream-io/cli from npm and references installing Tempo via curl | bash. Fetching and executing arbitrary packages/scripts at runtime (npx / curl|bash) is a supply-chain risk unless the package and install URL are verified. No homepage or source repo is provided in the metadata to validate the package owner.

Credentials

Registry metadata declares no required env vars, but the instructions require an API Key or a wallet/private key to authenticate and perform payments; they also direct storing credentials in ~/.config/chainstream/config.json and keys under ~/.config/chainstream/keys/. Asking an agent to import raw private keys or to let a CLI create and store a TEE-backed wallet is sensitive and should be explicitly justified and consented to. The skill does not declare these secrets in requires.env, making the sensitivity less obvious.

Persistence & Privilege

The skill itself does not set always:true and is user-invocable (normal). However runtime actions (CLI wallet/login, API key auto-save) create persistent artifacts on disk (~/.config/chainstream). That persistence is expected for a CLI-based integration but it increases the blast radius (stored API keys, private keys). The skill does not appear to modify other skills or system-wide agent settings.

What to consider before installing

Before installing or using this skill, consider the following: - Provenance: there is no homepage or source repo in the metadata. Verify @chainstream-io/cli on npm and the ChainStream project (official docs, GitHub repo, company site) before running npx or curl installers. - Avoid pasting private keys into agents: if asked to import a raw private key into the CLI, do not do so unless you fully trust the code and environment. Prefer a dashboard-issued API key (read-only) over importing private keys into an agent-managed CLI. - Be cautious with runtime installs: npx downloads code at runtime and the shared docs even suggest curl | bash for Tempo — running unknown install scripts is high risk. Only run installers from verified sources. - Payment behavior: the docs are inconsistent about auto-purchase on 402. Confirm whether the CLI will auto-select and pay a plan or will prompt you to pick a plan. Never allow autonomous payment without explicit user consent. - Persistent secrets: the CLI will save API keys and may write keys to ~/.config/chainstream. After testing, remove any stored secrets if you no longer want the agent to have them. If you want to proceed safely: ask the skill author for a source repo and package ownership proof, prefer using a dashboard API key (set via npx @chainstream-io/cli config set --key apiKey --value <key>) rather than wallet creation/import, and disable any automatic payment flows unless you manually confirm a chosen plan.

Flexible GraphQL interface to ChainStream's on-chain data warehouse. 22 cubes covering DEX trades, token analytics, wallet PnL, transfers, blocks, transactions, and more — across Solana, Ethereum, and BSC.

• 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 + token names)	GraphQL	joinXxx support
Custom aggregation (count, sum, avg with groupBy)	GraphQL	Metrics + dimension grouping
Complex filters (multi-condition WHERE, nested)	GraphQL	Full filter operator support
Time-series data with custom resolution	GraphQL	OHLC cube + time filters
Data not exposed by REST API	GraphQL	Direct access to all 22 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 → 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 '{"network":"eth"}'
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 22 cubes 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 {
  DEXTrades(network: sol, limit: {count: 25}, orderBy: Block_Time_DESC) {
    Block { Time }
    Trade { Buy { Currency { MintAddress } Amount PriceInUSD } Sell { Currency { MintAddress } Amount } Dex { ProtocolName } }
  }
}' --json

If the user has no subscription, CLI auto-handles x402 payment transparently — prompts for plan, pays, retries.

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

query {
  CubeName(network: sol|eth|bsc, limit: {count: N}, orderBy: Field_DESC, where: {...}) {
    FieldGroup { SubField }
    joinXxx { ... }
    count
  }
}

• network: Required on every cube. sol = Solana, eth = Ethereum, bsc = BSC.
• limit: {count: N, offset: M}. Default 25.
• orderBy: FieldPath_ASC or FieldPath_DESC. Most cubes default to Block_Time_DESC.
• where: {Group: {Field: {operator: value}}}.
• 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.

NEVER Do

• NEVER use Bitquery syntax ({ Solana { ... } } or { EVM { ... } }) — this is a completely different schema
• 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 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 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	Query syntax, filter operators, joinXxx rules, common mistakes	Before constructing any query
query-patterns.md	15+ 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.