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

# 第一個查詢

> 從 IDE 與 cURL 逐步執行你的第一個 GraphQL 查詢

<Note>
  **預計耗時**：約 5 分鐘
</Note>

## 準備工作

開始前請確認：

* 已註冊 ChainStream 賬號（[點此註冊](https://www.chainstream.io/dashboard)）
* 擁有 API Key（以 `cs_live_...` 開頭）

<Tip>
  GraphQL API 與 REST Data API 共用同一 API Key。若你已有 REST API 的 Key，可直接在此複用。
</Tip>

***

## 第一步：獲取 API Key

1. 登入 [ChainStream Dashboard](https://www.chainstream.io/dashboard)
2. 進入 **Applications**
3. 點選 **Create New App**（或選擇已有應用）
4. 複製你的 **API Key**

***

## 第二步：開啟 GraphQL IDE

訪問 ChainStream GraphQL IDE：

<Card title="GraphQL IDE" icon="code" href="https://ide.chainstream.io">
  [https://ide.chainstream.io](https://ide.chainstream.io)
</Card>

IDE 提供自動補全、語法高亮、內聯文件與查詢歷史 — 是探索 schema 與編寫查詢最快的方式。

***

## 第三步：配置鑑權

在 IDE 中開啟 **Headers** 面板（左下角），新增 API Key：

```json theme={null}
{
  "X-API-KEY": "your_api_key"
}
```

***

## 第四步：執行示例查詢

將以下查詢貼上到編輯器。它會拉取 **Solana 上最近 10 筆 DEX 成交**，含區塊時間、交易雜湊、買賣代幣資訊、數量、USD 價格與 DEX 協議名。

```graphql theme={null}
query {
  Solana {
    DEXTrades(
      limit: {count: 10}
      orderBy: {descending: Block_Time}
    ) {
      Block {
        Time
        Slot
      }
      Transaction {
        Hash
      }
      Trade {
        Buy {
          Currency { MintAddress }
          Amount
          PriceInUSD
        }
        Sell {
          Currency { MintAddress }
          Amount
        }
        Dex { ProtocolName }
      }
    }
  }
}
```

<Tip>
  [在 GraphQL IDE 中開啟](https://ide.chainstream.io) — 貼上上方查詢即可互動執行，並享受自動補全與 schema 瀏覽。
</Tip>

點選 **Play** 按鈕（或按 `Ctrl+Enter` / `Cmd+Enter`）執行。

***

## cURL 等價寫法

你也可以在終端執行相同查詢：

```bash theme={null}
curl -X POST "https://graphql.chainstream.io/graphql" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key" \
  -d '{
    "query": "{ Solana { DEXTrades(limit: {count: 10}, orderBy: {descending: Block_Time}) { Block { Time Slot } Transaction { Hash } Trade { Buy { Currency { MintAddress } Amount PriceInUSD } Sell { Currency { MintAddress } Amount } Dex { ProtocolName } } } } }"
  }'
```

***

## 響應示例

成功響應大致如下：

```json theme={null}
{
  "data": {
    "Solana": {
      "DEXTrades": [
        {
          "Block": {
            "Time": "2025-03-27T10:32:18Z",
            "Slot": 325847291
          },
          "Transaction": {
            "Hash": "4vKzR8g...x9bQ"
          },
          "Trade": {
            "Buy": {
              "Currency": { "MintAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" },
              "Amount": 1523.45,
              "PriceInUSD": 1.0001
            },
            "Sell": {
              "Currency": { "MintAddress": "So11111111111111111111111111111111111111112" },
              "Amount": 10.237
            },
            "Dex": { "ProtocolName": "Raydium" }
          }
        },
        {
          "Block": {
            "Time": "2025-03-27T10:32:17Z",
            "Slot": 325847289
          },
          "Transaction": {
            "Hash": "3mPqW7n...kR2J"
          },
          "Trade": {
            "Buy": {
              "Currency": { "MintAddress": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263" },
              "Amount": 48291037.12,
              "PriceInUSD": 0.00003152
            },
            "Sell": {
              "Currency": { "MintAddress": "So11111111111111111111111111111111111111112" },
              "Amount": 10.5
            },
            "Dex": { "ProtocolName": "Orca" }
          }
        }
      ]
    }
  },
  "extensions": {
    "credits": {
      "total": 50,
      "cubes": [
        { "cube": "DEXTrades", "credits": 50, "row_count": 10 }
      ]
    }
  }
}
```

***

## 理解響應

響應結構與查詢一一對應：

| 路徑                                | 說明                                       |
| :-------------------------------- | :--------------------------------------- |
| `Block.Time`                      | 區塊時間戳（ISO 8601）                          |
| `Block.Slot`                      | Solana slot 編號（Solana 特有）                |
| `Transaction.Hash`                | 鏈上交易雜湊                                   |
| `Trade.Buy.Currency.MintAddress`  | 買入資產的代幣地址                                |
| `Trade.Buy.Amount`                | 買入代幣數量                                   |
| `Trade.Buy.PriceInUSD`            | 成交時買入代幣的 USD 價格                          |
| `Trade.Sell.Currency.MintAddress` | 賣出資產的代幣地址                                |
| `Trade.Sell.Amount`               | 賣出代幣數量                                   |
| `Trade.Dex.ProtocolName`          | 執行成交的 DEX 協議（如 Raydium、Orca、PancakeSwap） |

<Info>
  `extensions.credits` 物件展示本次查詢消耗的計費額度與餘額。詳見 [計費與額度](/zh-Hant/graphql/billing/graphql-billing)。
</Info>

***

## 嘗試修改查詢

查詢跑通後，可以試試這些改法：

<AccordionGroup>
  <Accordion title="切換到 Ethereum">
    將根從 `Solana` 改為 `EVM(network: eth)` 並相應調整查詢體，以查詢 Ethereum DEX 成交（Uniswap、SushiSwap 等）。
  </Accordion>

  <Accordion title="新增時間篩選">
    透過 `where` 篩選最近一小時的成交：

    ```graphql theme={null}
    Solana {
      DEXTrades(
        limit: {count: 10}
        orderBy: {descending: Block_Time}
        where: {Block: {Time: {after: "2025-03-27T09:00:00Z"}}}
      ) { ... }
    }
    ```
  </Accordion>

  <Accordion title="查詢指定代幣">
    按代幣 mint 地址篩選，檢視該代幣的成交：

    ```graphql theme={null}
    Solana {
      DEXTrades(
        limit: {count: 10}
        orderBy: {descending: Block_Time}
        where: {Trade: {Buy: {Currency: {MintAddress: {is: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"}}}}}
      ) { ... }
    }
    ```
  </Accordion>

  <Accordion title="新增聚合">
    按 DEX 協議統計成交筆數：

    ```graphql theme={null}
    Solana {
      DEXTrades(
        where: {Block: {Time: {after: "2025-03-27T00:00:00Z"}}}
      ) {
        count
        Trade { Dex { ProtocolName } }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

***

## 下一步

<CardGroup cols={2}>
  <Card title="Schema 與資料模型" icon="diagram-project" href="/zh-Hant/graphql/schema/schema-overview">
    瀏覽全部 25 個 Cube、欄位型別、篩選運算子與聚合函式。
  </Card>

  <Card title="查詢示例" icon="flask" href="/zh-Hant/graphql/examples/dex-trades">
    檢視 DEX 成交、轉賬、OHLC、持有人等實際查詢示例。
  </Card>

  <Card title="GraphQL IDE 指南" icon="code" href="/zh-Hant/graphql/ide/introduction">
    掌握 IDE — 查詢模板、儲存查詢、變數面板與程式碼匯出。
  </Card>

  <Card title="計費與額度" icon="credit-card" href="/zh-Hant/graphql/billing/graphql-billing">
    瞭解查詢額度如何計算以及如何最佳化成本。
  </Card>
</CardGroup>