> ## 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 API 쿼리가 Credit Unit 시스템으로 어떻게 과금되는지 이해

## 개요

모든 GraphQL 쿼리는 쿼리 복잡도에 따라 동적으로 계산되는 \*\*Credit Unit(CU)\*\*을 소비합니다. 크레딧은 REST API와 동일한 과금 플랜에서 차감되며, API Key 하나로 둘 다 사용할 수 있습니다.

<Info>
  GraphQL API는 REST Data API와 동일한 API Key·과금 플랜을 공유합니다. GraphQL 쿼리로 소비한 크레딧은 전체 사용량에 포함됩니다.
</Info>

***

## 크레딧 계산 공식

크레딧은 Cube마다 **5요인 공식**으로 계산됩니다. 최종 CU는 조회 내용, 요청 행 수, 집계 사용 여부, 포함한 metric 수, 선택한 필드 수에 따라 달라집니다.

```
CU = ceil(BaseCost × LimitFactor × AggregationFactor × MetricFactor × ComplexityFactor) / 100
```

| 요인                    | 계산                                                  | 설명                                                                 |
| :-------------------- | :-------------------------------------------------- | :----------------------------------------------------------------- |
| **BaseCost**          | Cube별 내부 값                                          | 기본 테이블 크기·스캔 비용을 반영합니다. Cube마다 base cost가 다릅니다.                    |
| **LimitFactor**       | `ceil(limit / 100)`, 최소 1                           | 요청 행 수에 선형으로 비례합니다. 1–100행은 동일 비용, 101–200은 2배 등입니다.               |
| **AggregationFactor** | 1.0(없음), 1.5(GROUP BY), 2.0(HAVING)                 | 집계 또는 사후 집계 필터(`selectWhere`) 사용 시 더 큽니다.                          |
| **MetricFactor**      | `1.0 + (aggregate_count × 0.1)`                     | 집계 함수(`count`, `sum`, `avg` 등)마다 비용에 10%가 가산됩니다.                   |
| **ComplexityFactor**  | `min(1.0 + min(select_count, 250) / 50 × 0.2, 1.5)` | 선택 필드가 많을수록 비용이 증가하며 최대 1.5배로 캡됩니다. 필드 약 5개인 단순 쿼리는 요인이 약 1.02입니다. |

<Note>
  **0행 쿼리는 무료입니다.** 결과 행이 없으면 다른 요인과 관계없이 크레딧이 청구되지 않습니다.
</Note>

### 계산 예시

<AccordionGroup>
  <Accordion title="단순 쿼리: 10행, 5필드">
    ```
    BaseCost = 2000 (internal), LimitFactor = ceil(10/100) = 1
    AggregationFactor = 1.0, MetricFactor = 1.0
    ComplexityFactor = 1.0 + (5/50) × 0.2 = 1.02
    Internal = ceil(2000 × 1 × 1.0 × 1.0 × 1.02) = 2040
    CU = 2040 / 100 = 20.40 CU
    ```
  </Accordion>

  <Accordion title="대용량 쿼리: 500행, 5필드">
    ```
    BaseCost = 2000, LimitFactor = ceil(500/100) = 5
    AggregationFactor = 1.0, MetricFactor = 1.0
    ComplexityFactor = 1.02
    Internal = ceil(2000 × 5 × 1.0 × 1.0 × 1.02) = 10200
    CU = 10200 / 100 = 102.00 CU
    ```
  </Accordion>

  <Accordion title="집계 쿼리: GROUP BY + metric 2개, 500행">
    ```
    BaseCost = 2000, LimitFactor = ceil(500/100) = 5
    AggregationFactor = 1.5 (GROUP BY)
    MetricFactor = 1.0 + 2 × 0.1 = 1.2
    ComplexityFactor = 1.02
    Internal = ceil(2000 × 5 × 1.5 × 1.2 × 1.02) = 18360
    CU = 18360 / 100 = 183.60 CU
    ```
  </Accordion>

  <Accordion title="복잡 쿼리: 많은 필드 선택">
    ```
    BaseCost = 2000, LimitFactor = 1
    AggregationFactor = 1.0, MetricFactor = 1.0
    ComplexityFactor = min(1.0 + (250/50) × 0.2, 1.5) = 1.5 (capped)
    Internal = ceil(2000 × 1 × 1.0 × 1.0 × 1.5) = 3000
    CU = 3000 / 100 = 30.00 CU
    ```
  </Accordion>
</AccordionGroup>

<Tip>
  CU는 동적으로 계산되므로, 정확한 비용을 알려면 응답의 `extensions.credits` 필드를 확인하거나 IDE 상태 표시줄의 CU 표시를 보는 것이 가장 좋습니다.
</Tip>

***

## 응답: `extensions.credits`

모든 GraphQL 응답의 `extensions`에 크레딧 소비 정보가 포함됩니다.

```json theme={null}
{
  "data": {
    "Solana": {
      "DEXTrades": [ ... ]
    }
  },
  "extensions": {
    "credits": {
      "total": 20.4,
      "unit": "CU",
      "cubes": [
        {
          "cube": "DEXTrades",
          "credits": 20.4,
          "row_count": 10
        }
      ]
    }
  }
}
```

| 필드                  | 타입       | 설명                 |
| :------------------ | :------- | :----------------- |
| `total`             | `Float`  | 전체 쿼리에서 소비한 총 CU   |
| `unit`              | `String` | 항상 `"CU"`          |
| `cubes`             | `Array`  | Cube별 내역           |
| `cubes[].cube`      | `String` | 과금 엔진에서 쓰는 Cube 이름 |
| `cubes[].credits`   | `Float`  | 해당 Cube에 청구된 CU    |
| `cubes[].row_count` | `Int`    | 반환된 행 수            |

<Note>
  `extensions.credits`는 크레딧이 소비될 때(`total > 0`) 포함됩니다. 0행을 반환하는 쿼리는 청구되지 않습니다.
</Note>

***

## IDE에서 사용량 모니터링

[GraphQL IDE](https://ide.chainstream.io) 상태 표시줄에 각 쿼리 후 크레딧 소비가 표시됩니다.

* **CU 표시**: 소비한 총 CU
* **지연 시간**: 요청 소요 시간(ms)
* **응답 크기**: 페이로드 크기

***

## 크레딧 사용 최적화 팁

<CardGroup cols={3}>
  <Card title="필드는 적게" icon="minimize">
    필요한 dimension만 요청하세요. ComplexityFactor는 선택 필드 수에 따라 증가합니다.
  </Card>

  <Card title="limit는 적절히" icon="gauge">
    실용적인 범위에서 `limit.count`를 낮게 유지하세요. LimitFactor는 행이 100개 늘어날 때마다 배가됩니다.
  </Card>

  <Card title="사전 집계 Cube 활용" icon="layer-group">
    집계 데이터는 DWD Cube(DEXTrades)에 metric을 돌리기보다 DWM/DWS Cube(Pairs, Tokens, TokenHolders)를 우선하세요.
  </Card>
</CardGroup>

***

## 관련 문서

<CardGroup cols={2}>
  <Card title="결제 및 단위(일반)" icon="receipt" href="/ko/docs/platform/billing-payments/plans-and-units">
    ChainStream 과금 플랜, 단위 할당, 결제 수단 개요.
  </Card>

  <Card title="메트릭 및 집계" icon="chart-simple" href="/ko/graphql/schema/metrics-aggregation">
    집계 metric이 쿼리 크레딧에 미치는 영향.
  </Card>
</CardGroup>