> ## 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 엔드포인트 URL, 인증, 요청 형식, 지원 네트워크

## GraphQL 엔드포인트

모든 GraphQL 쿼리는 단일 엔드포인트로 전송됩니다:

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

**POST**와 **GET** 메서드 모두 지원됩니다.

| 메서드    | Content-Type          | 사용 사례                     |
| :----- | :-------------------- | :------------------------ |
| `POST` | `application/json`    | 모든 쿼리에 권장 — 변수와 복잡한 쿼리 지원 |
| `GET`  | 쿼리 문자열 (`?query=...`) | 간단한 쿼리, 브라우저 테스트, 캐싱 친화적  |

<Tip>
  프로덕션 워크로드에는 **POST**를 사용하세요. GET 요청은 쿼리를 URL에 인코딩하므로 길이 제한이 있고 복잡한 쿼리가 다루기 어려워집니다.
</Tip>

***

## 인증

`X-API-KEY` 헤더에 API Key를 전달하여 인증합니다. REST Data API와 동일한 API Key를 사용하므로 별도의 자격 증명이 필요하지 않습니다.

```
X-API-KEY: your_api_key
```

<Note>
  [ChainStream Dashboard](https://www.chainstream.io/dashboard) → **Applications** → **Create New App**에서 API Key를 발급받으세요. 키는 `cs_live_...`로 시작합니다.
</Note>

### 필수 헤더

| 헤더             | 값                  | 필수       |
| :------------- | :----------------- | :------- |
| `Content-Type` | `application/json` | 예 (POST) |
| `X-API-KEY`    | `cs_live_...`      | 예        |

***

## 요청 형식

GraphQL 요청 본문은 두 개의 필드를 가진 JSON 객체입니다:

| 필드          | 타입       | 설명                                |
| :---------- | :------- | :-------------------------------- |
| `query`     | `string` | GraphQL 쿼리 또는 뮤테이션 문자열            |
| `variables` | `object` | `$variable` 구문으로 쿼리에서 참조되는 선택적 변수 |

### POST 예제

<Tabs>
  <Tab title="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: 5}, orderBy: {descending: Block_Time}) { Block { Time } Trade { Buy { Currency { MintAddress } Amount } } } } }"
      }'
    ```
  </Tab>

  <Tab title="cURL (쿼리 파일)">
    복잡한 쿼리의 경우 쿼리를 파일에 저장하고 참조할 수 있습니다:

    ```bash theme={null}
    # Save query to file
    cat > query.graphql << 'EOF'
    {
      Solana {
        DEXTrades(limit: {count: 5}, orderBy: {descending: Block_Time}) {
          Block { Time }
          Trade {
            Buy {
              Currency { MintAddress }
              Amount
            }
          }
        }
      }
    }
    EOF

    # Send request
    curl -X POST "https://graphql.chainstream.io/graphql" \
      -H "Content-Type: application/json" \
      -H "X-API-KEY: your_api_key" \
      -d "{\"query\": \"$(cat query.graphql | tr '\n' ' ')\"}"
    ```
  </Tab>

  <Tab title="JavaScript (fetch)">
    ```javascript theme={null}
    const response = await fetch("https://graphql.chainstream.io/graphql", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-KEY": "your_api_key",
      },
      body: JSON.stringify({
        query: `{
          Solana {
            DEXTrades(limit: {count: 5}, orderBy: {descending: Block_Time}) {
              Block { Time }
              Trade { Buy { Currency { MintAddress } Amount } }
            }
          }
        }`,
      }),
    });

    const { data, extensions } = await response.json();
    console.log(data.Solana.DEXTrades);
    ```
  </Tab>

  <Tab title="Python (requests)">
    ```python theme={null}
    import requests

    resp = requests.post(
        "https://graphql.chainstream.io/graphql",
        headers={
            "Content-Type": "application/json",
            "X-API-KEY": "your_api_key",
        },
        json={
            "query": """{
                Solana {
                    DEXTrades(limit: {count: 5}, orderBy: {descending: Block_Time}) {
                        Block { Time }
                        Trade { Buy { Currency { MintAddress } Amount } }
                    }
                }
            }""",
        },
    )

    data = resp.json()
    print(data["data"]["Solana"]["DEXTrades"])
    ```
  </Tab>
</Tabs>

### GET 예제

```bash theme={null}
curl -G "https://graphql.chainstream.io/graphql" \
  -H "X-API-KEY: your_api_key" \
  --data-urlencode 'query={ Solana { DEXTrades(limit: {count: 5}, orderBy: {descending: Block_Time}) { Block { Time } } } }'
```

***

## 지원 네트워크

Cube 쿼리를 적절한 **Chain Group**으로 감싸서 네트워크를 선택합니다:

| Chain Group         | 블록체인            | Chain ID |
| :------------------ | :-------------- | :------- |
| `Solana`            | Solana          | —        |
| `EVM(network: eth)` | Ethereum        | 1        |
| `EVM(network: bsc)` | BNB Chain (BSC) | 56       |

```graphql theme={null}
# Solana
{ Solana { DEXTrades(limit: {count: 5}) { ... } } }

# Ethereum
{ EVM(network: eth) { DEXTrades(limit: {count: 5}) { ... } } }

# BSC
{ EVM(network: bsc) { DEXTrades(limit: {count: 5}) { ... } } }
```

***

## 응답 형식

모든 응답은 다음 구조의 JSON입니다:

```json theme={null}
{
  "data": {
    "Solana": {
      "DEXTrades": [
        { "Block": { "Time": "2025-03-27T10:15:30Z" }, "..." : "..." }
      ]
    }
  },
  "extensions": {
    "credits": {
      "total": 50,
      "cubes": [
        { "cube": "DEXTrades", "credits": 50, "row_count": 5 }
      ]
    }
  }
}
```

| 필드                         | 설명                                  |
| :------------------------- | :---------------------------------- |
| `data`                     | 쿼리 결과 — 쿼리의 형태와 일치                  |
| `errors`                   | 유효성 검사 또는 실행 오류가 있을 때만 존재           |
| `extensions.credits.total` | 이 쿼리에서 소비된 총 크레딧 단위                 |
| `extensions.credits.cubes` | Cube별 상세: Cube 이름, 부과된 크레딧, 반환된 행 수 |

<Note>
  `extensions.credits` 필드는 크레딧이 소비될 때 포함됩니다. 크레딧 계산 방법에 대한 자세한 내용은 [빌링 & 크레딧](/ko/graphql/billing/graphql-billing)을 참조하세요.
</Note>

### 오류 응답

쿼리가 잘못되었거나 실패하면 응답에 `errors` 배열이 포함됩니다:

```json theme={null}
{
  "data": null,
  "errors": [
    {
      "message": "Unknown field 'InvalidField' on type 'DEXTrades'",
      "locations": [{ "line": 3, "column": 5 }]
    }
  ]
}
```

<Tip>
  애플리케이션에 통합하기 전에 [GraphQL IDE](https://ide.chainstream.io)를 사용하여 쿼리를 인터랙티브하게 검증하세요. IDE는 자동 완성과 인라인 오류 강조 기능을 제공합니다.
</Tip>

***

## 다음 단계

<CardGroup cols={2}>
  <Card title="첫 번째 쿼리 실행" icon="play" href="/ko/graphql/getting-started/first-query">
    IDE 또는 cURL에서 실제 쿼리를 실행하는 단계별 튜토리얼을 따라해 보세요.
  </Card>

  <Card title="스키마 탐색" icon="diagram-project" href="/ko/graphql/schema/schema-overview">
    25개 Cube, 필드 타입, 필터링 연산자, 집계 함수를 살펴보세요.
  </Card>
</CardGroup>