chainstream-graphql Skill

概述

chainstream-graphql skill 让 AI Agent 通过 GraphQL 灵活地、类 SQL 地访问 ChainStream 的链上数据仓库。当预置的 REST/MCP 端点表达能力不够时，它是合适的工具——跨 cube JOIN、自定义聚合、多条件过滤、自定义时间序列粒度，或只有 GraphQL 才暴露的数据（例如 PolyMarket 预测 cube）。

模式：Tool（只读，不签名）
端点：https://graphql.chainstream.io/graphql（经 APISIX 路由）
CLI：npx @chainstream-io/cli graphql
认证：X-API-KEY 传入 API Key，或使用 SIWX 钱包 token
计费：与 REST 共用同一个 API Key / 订阅池（x402 / MPP 由 CLI 自动处理）
范围：3 个链组、27 个 cube——Solana、EVM(network: eth | bsc | polygon)、Trading

何时使用

与 chainstream-data 的选用矩阵：

场景	使用	原因
标准代币搜索、市场趋势、钱包画像	`chainstream-data`	有预置的 REST / MCP，更简单
跨 cube JOIN（trades + transfers、pools + events）	chainstream-graphql	支持 `joinXxx`
自定义聚合（`groupBy` 配合 count / sum / avg）	chainstream-graphql	指标 + 维度分组
多条件过滤（嵌套、通过 `any` 实现 OR）	chainstream-graphql	完整过滤算子
带自定义粒度 / 桶的时间序列	chainstream-graphql	时间区间分桶
预测市场数据（Polygon 上的 PolyMarket）	chainstream-graphql	`PredictionTrades / Managements / Settlements` cube

集成路径

通道矩阵

GraphQL 是一个接口，被不同调用方使用：

操作	CLI 命令	SDK 方法
列出全部 cube（概要）	`graphql schema --summary`	无——用 CLI 发现
深入单个 cube	`graphql schema --type <CubeName>`	无
完整 schema 参考	`graphql schema --full`	无
强制刷新缓存 schema	`graphql schema --summary --refresh`	无
内联查询	`graphql query --query '<gql>'`	`client.graphql.query(gql)`
从文件查询	`graphql query --file ./q.graphql`	`client.graphql.query(fs.readFileSync(...))`
带变量查询	`graphql query --query '...' --var '{"k":"v"}'`	`client.graphql.query(gql, vars)`
机器可读输出	追加 `--json`	原生 JSON 返回

AI 工作流

探索 Schema

Agent 不清楚用哪个 cube 时，总是从这里开始。

npx @chainstream-io/cli graphql schema --summary
npx @chainstream-io/cli graphql schema --type DEXTrades

--summary 返回 27 个 cube 按链（EVM / Solana / Trading）分组的紧凑目录，包括顶层字段和说明。--type 展开单个 cube 的字段树以便构造查询。

构造并执行查询

Schema 以 链组包装器 作为顶层入口。

Solana
EVM
Trading

query {
  Solana {
    DEXTrades(
      limit: { count: 25 }
      orderBy: { descending: Block_Time }
    ) {
      Block { Time }
      Trade {
        Buy  { Currency { MintAddress } Amount PriceInUSD }
        Sell { Currency { MintAddress } Amount }
        Dex  { ProtocolName }
      }
    }
  }
}

query {
  EVM(network: eth) {
    DEXTrades(
      limit: { count: 25 }
      orderBy: { descending: Block_Time }
      where: { Trade: { Buy: { Amount: { gt: "0" } } } }
    ) {
      Block { Time }
      Trade { Buy { Currency { Symbol } Amount } Sell { Currency { Symbol } Amount } }
    }
  }
}

query {
  Trading {
    Pairs(
      tokenAddress: { is: "So11111111111111111111111111111111111111112" }
      limit: { count: 24 }
    ) {
      TimeMinute
      Price { Open High Low Close }
    }
  }
}

通过 CLI 执行：

npx @chainstream-io/cli graphql query --file ./query.graphql --json

或内联：

npx @chainstream-io/cli graphql query \
  --query 'query { Solana { DEXTrades(limit:{count:5}) { Block { Time } } } }' \
  --json

查询构造速查

链组包装器：顶层必需。Solana、EVM(network: ...) 或 Trading。
network：仅 EVM 可用。取值：eth、bsc、polygon。
limit：{ count: N, offset: M }。默认 25。
orderBy：{ descending: Field } / { ascending: Field }。计算字段用 { descendingByField: "field_name" }。
where：{ Group: { Field: { operator: value } } }。OR 条件通过 any: [{...}, {...}]。
DateTime 格式："YYYY-MM-DD HH:MM:SS"——不带 T、不带 Z（ClickHouse 要求）。
DateTime 过滤器：since、till、after、before——禁止在 DateTime 字段上用 gt / lt。
joinXxx：到关联 cube 的 LEFT JOIN。优先于多次查询。
dataset 包装参数：realtime、archive、combined（默认）。
aggregates 包装参数：yes、no、only。

链组与 Cube

链组	包装器	Cube
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 cube 仅在 polygon 网络可用。

安全规则

以下规则由 skill 强制执行，以保证查询正确并避免浪费配额。

规则	原因
禁止使用扁平的 `CubeName(network: sol)`——必须放到链组包装器里	服务端拒绝未包装的查询
禁止猜字段名——先跑 `graphql schema --type <cube>`	避免反复的 “field does not exist” 报错
禁止用 ISO-8601 `"2026-03-31T00:00:00Z"`——用 `"2026-03-31 00:00:00"`	ClickHouse DateTime 格式
DateTime 禁止 `gt` / `lt`——用 `since` / `after` / `before` / `till`	DateTime 过滤器有专用名
能用 `joinXxx` 合并就不要拆成多次查询	一次计费请求代替多次
禁止自动选择付费套餐——始终让用户选	计费知情同意

错误恢复

错误	恢复方式
401 / “Not authenticated”	`config auth`——未登录则跑 `login`（首次自动赠送 nano trial，50K CU）。随后重试。
402 / “Payment required”	`plan status`；无订阅则 `wallet pricing` → `plan purchase --plan <choice>`。参见 x402 支付。
`GraphQL error: field X does not exist`	用 `graphql schema --type <cube>` 复核字段名。
429	等 1 秒，指数退避。
5xx	2 秒后重试一次。

chainstream-data

代币、市场、钱包分析的标准 REST/MCP 查询

chainstream-defi

分析之后执行交易——swap、发币

GraphQL 接入方式

端点参考、认证、schema 概览

CLI `graphql` 子命令

chainstream graphql schema 和 query 参考

数据产品

接入方式

AI Agents

合规 (KYT/KYA)

教程

实战范例

平台

生态

参考

chainstream-graphql Skill

概述

何时使用

集成路径

通道矩阵

AI 工作流

探索 Schema

构造并执行查询

查询构造速查

链组与 Cube

安全规则

错误恢复

相关

chainstream-data

chainstream-defi

GraphQL 接入方式

CLI `graphql` 子命令

​概述

​何时使用

​集成路径

​通道矩阵

​AI 工作流

​探索 Schema

​构造并执行查询

​查询构造速查

​链组与 Cube

​安全规则

​错误恢复

​相关

chainstream-data

chainstream-defi

GraphQL 接入方式

CLI `graphql` 子命令

概述

何时使用

集成路径

通道矩阵

AI 工作流

探索 Schema

构造并执行查询

查询构造速查

链组与 Cube

安全规则

错误恢复

相关