> ## 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 钱包令牌（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](/zh-Hant/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="/zh-Hant/graphql/schema/schema-overview">
    型別、關係與約定。
  </Card>

  <Card title="入門" icon="rocket" href="/zh-Hant/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 技能" icon="brain" href="/zh-Hant/docs/ai-agents/agent-skills/chainstream-graphql">
    面向 GraphQL 工作流的結構化 Agent Skill。
  </Card>

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

  <Card title="SDK" icon="box" href="/zh-Hant/docs/access-methods/sdks">
    透過 codegen 的型別化 GraphQL 封裝。
  </Card>
</CardGroup>