> ## 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 지갑 토큰 (에이전트 / 호스트 지갑)
-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](/ko/docs/access-methods/cli)에는 `graphql schema`(탐색용)와 `graphql query`(실행용)가 내장되어 있습니다 — 빠른 확인이나 셸 자동화를 위해 클라이언트 라이브러리를 연결할 필요가 없습니다:

```bash theme={null}
# 27개 큐브 탐색
chainstream graphql schema --summary
chainstream graphql schema --type DEXTrades

# 파일에서 쿼리 실행
chainstream graphql query --file ./query.graphql --json
```

## 스키마

<CardGroup cols={2}>
  <Card title="Schema 개요" icon="diagram-project" href="/ko/graphql/schema/schema-overview">
    타입, 관계, 규칙.
  </Card>

  <Card title="Getting started" icon="rocket" href="/ko/graphql/getting-started/overview">
    첫 쿼리 완전 가이드.
  </Card>
</CardGroup>

## 다음 단계

<CardGroup cols={2}>
  <Card title="GraphQL IDE" icon="terminal" href="https://graphql.chainstream.io">
    스키마를 탐색하고 쿼리를 인터랙티브하게 실행.
  </Card>

  <Card title="chainstream-graphql 스킬" icon="brain" href="/ko/docs/ai-agents/agent-skills/chainstream-graphql">
    GraphQL 워크플로우를 위한 구조화된 Agent Skill.
  </Card>

  <Card title="CLI `graphql` 서브명령" icon="terminal" href="/ko/docs/access-methods/cli#graphql-서브명령">
    `chainstream graphql schema` 및 `query` 레퍼런스.
  </Card>

  <Card title="SDK" icon="box" href="/ko/docs/access-methods/sdks">
    codegen을 통한 타입드 GraphQL 래퍼.
  </Card>
</CardGroup>