> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainstream.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 概览

> ChainStream GraphQL — 面向多链链上数据的 OLAP 分析型 GraphQL 接口

<Info>
  ChainStream GraphQL 是一套 OLAP 分析 API，通过单一 GraphQL 端点暴露多链链上数据（Solana、Ethereum、BSC、Polygon）。按需查询字段、即时聚合、交互式探索 Schema —— 底层由高性能 OLAP 数据库支撑。
</Info>

## 什么是 ChainStream GraphQL

ChainStream GraphQL 为链上分析数据提供 **声明式查询接口**。无需调用大量固定形态的 REST 端点，只需编写一条 GraphQL 查询，即可精确指定所需数据、过滤条件与聚合方式。

服务基于 **activecube-rs**，根据 **Cube** 定义动态生成 GraphQL Schema —— 每个 Cube 代表一种分析数据模型（例如 DEX 成交、代币转账、OHLC K 线）。查询会被编译为优化后的 SQL，并在高性能 OLAP 数据库上执行。

***

## GraphQL 与 REST Data API

<div style={{ overflowX: 'auto', width: '100%' }}>
  |          | **GraphQL API**                        | **REST Data API**              |
  | :------- | :------------------------------------- | :----------------------------- |
  | **查询方式** | 声明式 — 自定义形状、过滤与聚合                      | 命令式 — 固定端点与预定义参数               |
  | **字段选择** | 客户端只取需要的字段                             | 服务端返回固定响应结构                    |
  | **聚合**   | 单次查询内置 `count`、`sum`、`avg`、`min`、`max` | 仅预定义的聚合端点                      |
  | **端点**   | 所有数据模型共用一个端点                           | 每个资源一个端点                       |
  | **分页**   | 查询参数中的 `limit` + `offset`              | 查询参数中的 `limit` + `offset` / 游标 |
  | **更适合**  | 分析、大盘、灵活探索                             | 简单查询、实时价格、钱包余额                 |
  | **延迟**   | 侧重吞吐                                   | 侧重低延迟单资源读取                     |
</div>

<Tip>
  需要灵活分析查询时（聚合成交、按时间段算 PnL、自建大盘）用 **GraphQL**；需要快速简单查询（当前代币价格、钱包余额）时用 **REST API**。
</Tip>

***

## 核心优势

<CardGroup cols={3}>
  <Card title="单一端点" icon="bullseye">
    一个 URL 覆盖 4 条链上的 25 个数据 Cube。无需端点爆炸 —— 只改查询即可。
  </Card>

  <Card title="客户端自选字段" icon="filter">
    只请求需要的列。避免过度获取与不足获取 —— 适合带宽受限的客户端。
  </Card>

  <Card title="内置聚合" icon="chart-column">
    在查询中直接计算 `count`、`sum`、`avg`、`min`、`max`，无需后置处理。
  </Card>
</CardGroup>

***

## 支持的链

| 网络 ID     | 区块链             | 链组     | 覆盖范围                                                        |
| :-------- | :-------------- | :----- | :---------------------------------------------------------- |
| `eth`     | Ethereum        | EVM    | 完整 DEX、转账、余额变动、事件、追踪、代币统计                                   |
| `bsc`     | BNB Chain (BSC) | EVM    | 完整 DEX、转账、余额变动、事件、追踪、代币统计                                   |
| `polygon` | Polygon         | EVM    | 预测市场（PredictionTrades/Managements/Settlements）。其他 Cube 部署中。 |
| `sol`     | Solana          | Solana | 完整 DEX、转账、指令、持币者、OHLC、PnL                                   |

<Note>
  查询按三个 **链组** 组织：**EVM**（需要 `network` 参数）、**Solana** 与 **Trading**（跨链 OHLC 与代币统计）。详见 [链组](/cn/graphql/schema/chain-groups)。
</Note>

***

## 可用数据 Cube

25 个 Cube 分布在三个链组中，每个对应一种分析模型：

<AccordionGroup>
  <Accordion title="DEX 交易">
    * **DEXTrades** — 单笔 DEX 换币事件，含买卖数量、价格与 DEX 协议信息
    * **DEXTradeByTokens** — 按代币索引的 DEX 成交，便于按代币查询
    * **DEXOrders** — DEX 订单事件，含限价单 *（仅 Solana）*
  </Accordion>

  <Accordion title="池子与流动性">
    * **DEXPoolEvents** — DEX 池子加减流动性事件
    * **DEXPools** — DEX 池子快照，含当前储备与元数据
    * **DEXPoolSlippages** — 池子滑点数据 *（仅 EVM）*
    * **TokenSupplyUpdates** — 影响代币供应的铸造与销毁事件
  </Accordion>

  <Accordion title="代币与转账">
    * **Transfers** — 代币转账事件，含收发方、数量与美元计价
    * **BalanceUpdates** — 按代币的钱包余额变动事件
    * **TokenHolders** — 代币当前持币列表与分布
    * **WalletTokenPnL** — 钱包-代币维度的 PnL
  </Accordion>

  <Accordion title="交易分析（跨链）">
    * **Pairs** — 可配置时间间隔的 OHLC K 线（旧称 OHLC）
    * **Tokens** — 按代币的聚合成交统计：成交量、成交笔数、独立交易者（旧称 TokenTradeStats）
  </Accordion>

  <Accordion title="链上基础设施">
    * **Blocks** — 区块级数据（时间戳、高度、矿工/验证者）
    * **Transactions** — 交易级数据（哈希、状态、gas/手续费）
    * **TransactionBalances** — 单笔交易内的余额变动
    * **Events** — 智能合约事件日志 *（仅 EVM）*
    * **Calls** — 内部调用追踪 *（仅 EVM）*
    * **Instructions** — 指令级数据 *（仅 Solana）*
    * **InstructionBalanceUpdates** — 指令级余额变动 *（仅 Solana）*
  </Accordion>

  <Accordion title="奖励与网络">
    * **Rewards** — 验证者/质押奖励 *（仅 Solana）*
    * **MinerRewards** — 矿工/验证者奖励 *（仅 EVM）*
    * **Uncles** — 叔块数据 *（仅 EVM）*
  </Accordion>

  <Accordion title="预测市场">
    * **PredictionTrades** — 预测市场成交事件 *（EVM — Polygon）*
    * **PredictionManagements** — 预测市场管理事件 *（EVM — Polygon）*
    * **PredictionSettlements** — 预测市场结算事件 *（EVM — Polygon）*
  </Accordion>
</AccordionGroup>

***

## 关键查询参数

除常规过滤与分页外，ChainStream GraphQL 在链组级别还支持两个重要参数：

| 参数               | 取值                                  | 说明                    |
| :--------------- | :---------------------------------- | :-------------------- |
| **`dataset`**    | `realtime`、`archive`、`combined`（默认） | 控制数据源范围 —— 仅近期、仅历史或全量 |
| **`aggregates`** | `yes`、`no`、`only`                   | 是否使用预聚合表以加速分析查询       |

<Tip>
  用法与示例见 [Dataset 与 Aggregates](/cn/graphql/schema/dataset-aggregates)。
</Tip>

***

## 架构

```mermaid theme={null}
graph LR
    A[Your App / AI Agent] --> B[GraphQL IDE]
    A --> C[Any GraphQL Client]
    B --> D[APISIX Gateway]
    C --> D
    D -->|Auth + Rate Limit| E[chainstream-graphql]
    E -->|"activecube-rs (GraphQL to SQL)"| F[(OLAP Database)]
```

<Info>
  所有请求经 APISIX 网关做认证与限流。`chainstream-graphql` 将 GraphQL 编译为优化 SQL，在 OLAP 分析库上执行。
</Info>

***

## 下一步

<CardGroup cols={3}>
  <Card title="端点与认证" icon="key" href="/cn/graphql/getting-started/endpoints">
    配置端点 URL、认证头与请求/响应格式。
  </Card>

  <Card title="第一条查询" icon="play" href="/cn/graphql/getting-started/first-query">
    从 IDE 或 cURL 逐步运行第一条 GraphQL 查询。
  </Card>

  <Card title="GraphQL IDE" icon="code" href="/cn/graphql/ide/introduction">
    使用带自动补全、查询模板与代码导出的交互式 GraphQL IDE。
  </Card>
</CardGroup>