> ## 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.

# GraphQL

> 灵活、分析型的查询——一次请求里跨数据产品 JOIN 出你要的答案。

GraphQL 端点适合你想 **塑形响应** 的场景——在一次请求里精确挑选跨多个数据产品的字段。如果 REST 是"取这一个东西"，GraphQL 就是"回答这一个分析问题"。

## 端点

```
POST https://graphql.chainstream.io/graphql
```

或者在 [GraphQL IDE](https://graphql.chainstream.io) 里交互式探索。

## 鉴权

两种等价路径——按你客户端的情况选：

```bash theme={null}
# API Key（浏览器、服务端、大部分客户端）
-H "X-API-KEY: $CHAINSTREAM_API_KEY"
-H "Content-Type: application/json"

# SIWX 钱包 token（Agent / 宿主钱包）
-H "Authorization: SIWX <token>"
-H "Content-Type: application/json"
```

GraphQL 与 REST 共用同一个 API Key 和订阅配额——无需单独购买。

## 第一个查询

```graphql theme={null}
query TopSolanaTokens {
  tokens(chain: SOLANA, orderBy: VOLUME_24H_DESC, limit: 5) {
    address
    symbol
    priceUsd
    marketCap
    recentTrades(limit: 3) {
      timestamp
      sizeUsd
      side
    }
  }
}
```

一次请求返回代币、元数据与最近成交——没有 N+1 回环。

## 什么时候用

* 跨多个数据产品的分析型查询
* 字段多又不想过度抓取的看板
* 报表 / BI 负载
* 服务端渲染，预先塑形响应

**不建议用** 的场景：实时流（用 WebSocket/Kafka）、REST 缓存更便宜的热读。

## 从 CLI 调用

[`chainstream` CLI](/cn/docs/access-methods/cli) 自带 `graphql schema`（探索）与 `graphql query`（执行）子命令——做快速检查或 shell 自动化时，无需专门接入客户端库：

```bash theme={null}
# 探索 27 个 cube
chainstream graphql schema --summary
chainstream graphql schema --type DEXTrades

# 从文件运行查询
chainstream graphql query --file ./query.graphql --json
```

## Schema

<CardGroup cols={2}>
  <Card title="Schema 总览" icon="diagram-project" href="/cn/graphql/schema/schema-overview">
    类型、关系与约定。
  </Card>

  <Card title="入门" icon="rocket" href="/cn/graphql/getting-started/overview">
    第一个查询的完整走读。
  </Card>
</CardGroup>

## 下一步

<CardGroup cols={2}>
  <Card title="GraphQL IDE" icon="terminal" href="https://graphql.chainstream.io">
    交互式探索 schema 与跑查询。
  </Card>

  <Card title="chainstream-graphql skill" icon="brain" href="/cn/docs/ai-agents/agent-skills/chainstream-graphql">
    面向 GraphQL 工作流的结构化 Agent Skill。
  </Card>

  <Card title="CLI `graphql` 子命令" icon="terminal" href="/cn/docs/access-methods/cli#graphql-subcommand">
    `chainstream graphql schema` 与 `query` 参考。
  </Card>

  <Card title="SDK" icon="box" href="/cn/docs/access-methods/sdks">
    通过 codegen 的类型化 GraphQL 封装。
  </Card>
</CardGroup>