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

# FAQ

> ChainStream 자주 묻는 질문

## 계정 및 인증

<AccordionGroup>
  <Accordion title="Access Token은 어떻게 발급하나요?">
    1. [ChainStream Dashboard](https://www.chainstream.io/dashboard)에 로그인
    2. **Apps** 페이지로 이동
    3. **Create New App** 클릭
    4. Client ID와 Client Secret 확인
    5. Client ID와 Client Secret을 사용하여 Auth 서비스에서 Access Token(JWT) 요청

    자세한 내용은 [인증 문서](/ko/docs/platform/authentication/api-keys-oauth)를 참조하세요.
  </Accordion>
</AccordionGroup>

***

## 데이터 관련

<AccordionGroup>
  <Accordion title="지원하는 블록체인은 무엇인가요?">
    현재 지원하는 체인:

    | 체인       | 상태   | 비고             |
    | :------- | :--- | :------------- |
    | Ethereum | ✅ 지원 | 메인넷 및 주요 L2 포함 |
    | Solana   | ✅ 지원 |                |
    | BSC      | ✅ 지원 |                |
    | Polygon  | ✅ 지원 |                |
    | Arbitrum | ✅ 지원 |                |
    | Optimism | ✅ 지원 |                |
    | Base     | ✅ 지원 |                |
    | Tron     | ✅ 지원 |                |

    자세한 내용은 [실시간 스트리밍](/ko/docs/access-methods/websocket)을 참조하세요.
  </Accordion>

  <Accordion title="데이터 지연 시간은 어느 정도인가요?">
    | 데이터 유형             | 지연           |
    | :----------------- | :----------- |
    | 실시간 가격 (WebSocket) | \< 2ms (P99) |
    | REST API 쿼리        | \< 100ms     |
    | 히스토리 데이터 쿼리        | \< 500ms     |

    지연 시간은 네트워크 상태 및 데이터 복잡도에 따라 달라질 수 있습니다.
  </Accordion>

  <Accordion title="데이터 업데이트 주기는 어느 정도인가요?">
    | 데이터 유형         | 업데이트 주기          |
    | :------------- | :--------------- |
    | 토큰 가격          | 실시간 (각 거래 시 트리거) |
    | 지갑 잔고          | 블록마다 업데이트        |
    | Smart Money 라벨 | 일일 업데이트          |

    WebSocket을 사용하면 가장 실시간에 가까운 데이터 푸시를 받을 수 있습니다.
  </Accordion>
</AccordionGroup>

***

## 요금 관련

<AccordionGroup>
  <Accordion title="무료 플랜의 제한 사항은 무엇인가요?">
    무료 플랜 제한:

    * **할당량:** 월 30K Units
    * **요청 속도:** 10 요청/초
    * **데이터 지연:** 1\~2초 지연 발생 가능
    * **SLA:** 보장 없음
    * **초과:** 할당량 소진 시 403 오류 반환, 다음 달 초기화

    개발 테스트 및 POC에 적합하며, 프로덕션 환경에는 권장하지 않습니다.
  </Accordion>

  <Accordion title="현재 사용량은 어떻게 확인하나요?">
    1. [Dashboard](https://www.chainstream.io/dashboard)에 로그인
    2. **Usage** 페이지에서 이번 달 사용량, 잔여 할당량, 과거 추이 확인
  </Accordion>

  <Accordion title="지원하는 결제 방법은 무엇인가요?">
    | 방법                            | 지원 플랜               |
    | :---------------------------- | :------------------ |
    | 신용카드 (Visa, MasterCard, AMEX) | 전체 플랜               |
    | 암호화폐 (USDT, USDC)             | Starter 이상          |
    | 은행 이체                         | Enterprise / Custom |

    암호화폐 결제는 ERC-20 및 TRC-20 네트워크를 지원합니다.
  </Accordion>

  <Accordion title="언제든지 업그레이드 또는 다운그레이드할 수 있나요?">
    * **업그레이드:** 즉시 적용, 비례 요금 부과
    * **다운그레이드:** 다음 청구 주기부터 적용

    Dashboard → Billing → Subscription에서 관리할 수 있습니다.
  </Accordion>

  <Accordion title="미사용 할당량은 이월되나요?">
    아니요. 월간 할당량은 월말에 초기화되며 이월되지 않습니다. 실제 사용량에 맞는 플랜을 선택하세요.
  </Accordion>
</AccordionGroup>

***

## 기술 문제

<AccordionGroup>
  <Accordion title="429 또는 403 오류가 발생하면 어떻게 하나요?">
    * **429 오류**: 요청 속도 초과
    * **403 오류**: 할당량 소진

    **문제 해결:**

    1. **429 - 속도 제한 확인**
       * 무료 플랜: 10 요청/분
       * 유료 플랜: [API 보안](/ko/docs/platform/security/api-security) 참조

    2. **403 - 할당량 소진 확인**
       * Dashboard → Usage에서 잔여 할당량 확인
       * 유료 플랜은 추가 할당량 구매로 서비스 복구 가능

    **해결 방법:**

    * 429: 요청 스로틀링 또는 지수 백오프 재시도 구현
    * 403: 추가 할당량 구매 또는 플랜 업그레이드
    * WebSocket을 사용하여 폴링 대신 요청 수 감소

    ```javascript theme={null}
    // Error handling example
    async function handleApiError(error) {
      if (error.status === 429) {
        // Rate limited, wait and retry
        await sleep(1000);
        return retry();
      } else if (error.status === 403) {
        // Quota exhausted, need to purchase additional quota
        console.error('Quota exhausted, please purchase additional quota in Dashboard');
      }
    }
    ```
  </Accordion>

  <Accordion title="WebSocket 연결 끊김은 어떻게 처리하나요?">
    자동 재연결 메커니즘 구현을 권장합니다:

    ```javascript theme={null}
    class ChainStreamWebSocket {
      constructor(baseUrl, accessToken) {
        this.baseUrl = baseUrl;
        this.accessToken = accessToken;
        this.reconnectDelay = 1000;
        this.maxReconnectDelay = 30000;
        this.connect();
      }

      connect() {
        // Pass token via URL parameter
        const url = `${this.baseUrl}?token=${this.accessToken}`;
        this.ws = new WebSocket(url);
        this.ws.onopen = () => {
          console.log('Connected');
          this.reconnectDelay = 1000; // Reset delay
        };
        this.ws.onclose = () => {
          console.log('Disconnected, reconnecting...');
          setTimeout(() => this.connect(), this.reconnectDelay);
          // Exponential backoff
          this.reconnectDelay = Math.min(
            this.reconnectDelay * 2,
            this.maxReconnectDelay
          );
        };
        this.ws.onerror = (error) => {
          console.error('WebSocket error:', error);
        };
      }
    }
    ```

    **재연결 팁:**

    * 지수 백오프 사용 (1s → 2s → 4s → ... → 30s)
    * 최대 재연결 지연 설정 (예: 30초)
    * 재연결 성공 후 데이터 재구독
  </Accordion>

  <Accordion title="API 응답 형식은 무엇인가요?">
    모든 API는 JSON 형식을 반환합니다.

    **성공 응답:**

    ```json theme={null}
    {
      "chain": "solana",
      "address": "So11111111111111111111111111111111111111112",
      "name": "Wrapped SOL",
      "symbol": "SOL",
      "decimals": 9,
      "price": 95.42
    }
    ```

    **오류 응답:**

    ```json theme={null}
    {
      "error": {
        "code": "INVALID_TOKEN",
        "message": "Token not found"
      }
    }
    ```

    일반적인 오류 코드는 [오류 코드](/ko/docs/reference/error-codes)를 참조하세요.
  </Accordion>

  <Accordion title="API 요청을 디버깅하려면 어떻게 하나요?">
    **방법 1: API Playground 사용**

    [API Reference](/ko/api-reference/overview) 페이지의 "Try It" 기능을 사용하여 코드 작성 없이 테스트할 수 있습니다.

    **방법 2: cURL 사용**

    `-v` 플래그를 추가하여 상세한 요청 정보를 확인:

    ```bash theme={null}
    curl -v "https://api.chainstream.io/v1/token/{chain}/{address}/metadata" \
      -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
    ```
  </Accordion>
</AccordionGroup>

***

## KYT/KYA 관련

<AccordionGroup>
  <Accordion title="KYT와 KYA의 차이점은 무엇인가요?">
    | 기능         | KYA (주소 검증)           | KYT 보고서          |
    | :--------- | :-------------------- | :--------------- |
    | 목적         | 주소 위험도 및 프로필 분석       | 거래 수준 위험 보고서     |
    | 입력         | 지갑 주소                 | 거래 해시 또는 주소      |
    | 출력         | 위험 수준 + 주소 유형 + 위험 노출 | 거래 관련 위험 분석      |
    | 대표적인 사용 사례 | 사용자 등록/입금 전 주소 심사     | 특정 거래의 컴플라이언스 검사 |

    자세한 내용은 [보안 컴플라이언스 문서](/ko/docs/compliance/overview)를 참조하세요.
  </Accordion>

  <Accordion title="Address Verification은 어떤 정보를 반환하나요?">
    주소 검증은 다음 필드를 반환합니다:

    | 필드             | 설명       | 예시 값                                  |
    | :------------- | :------- | :------------------------------------ |
    | Risk           | 위험 수준    | Low, Medium, High, Severe             |
    | Status         | 검증 상태    | COMPLETE, PENDING                     |
    | Address Type   | 주소 유형    | PRIVATE\_WALLET, EXCHANGE, CONTRACT 등 |
    | Risk Exposures | 위험 노출 상세 | 위험 라벨 및 관련 금액                         |
  </Accordion>

  <Accordion title="위험 수준은 어떻게 해석하나요?">
    Address Verification은 다음 위험 수준을 반환합니다:

    | 위험 수준  | 의미                      | 권장 조치          |
    | :----- | :---------------------- | :------------- |
    | Low    | 저위험, 의심스러운 연관 없음        | 정상 처리          |
    | Medium | 중위험, 일부 의심스러운 연관        | 수동 검토 권장       |
    | High   | 고위험, 상당한 의심스러운 연관       | 거부 또는 강화 검토 권장 |
    | Severe | 심각한 위험, 제재/불법 단체와 직접 연관 | 거부 강력 권장       |

    **참고:** 구체적인 처리 정책은 비즈니스 컴플라이언스 요구사항에 따라 설정해야 합니다. 위 내용은 참고용 제안입니다.
  </Accordion>

  <Accordion title="Risk Exposures에는 어떤 위험 라벨이 있나요?">
    Risk Exposures는 주소와 다양한 위험 단체와의 연관을 표시합니다. 일반적인 라벨은 다음과 같습니다:

    **고위험 라벨 (Severe):**

    | 라벨                      | 설명            |
    | :---------------------- | :------------ |
    | sanctioned entity       | 제재 대상 단체와 연관  |
    | sanctioned jurisdiction | 제재 대상 관할권과 연관 |
    | terrorist financing     | 테러 자금 조달과 연관  |

    **중립/저위험 라벨:**

    | 라벨                     | 설명                  |
    | :--------------------- | :------------------ |
    | bridge                 | 크로스체인 브릿지를 통한 자금 이동 |
    | decentralized exchange | DEX를 통한 거래          |
    | atm                    | 암호화폐 ATM을 통한 거래     |

    **기타 위험 라벨:**

    | 라벨       | 설명         |
    | :------- | :--------- |
    | mixer    | 믹싱 서비스 이용  |
    | gambling | 도박 플랫폼과 연관 |
    | darknet  | 다크넷 마켓과 연관 |

    각 라벨에는 다음이 표시됩니다:

    * **direct / indirect**: 직접 또는 간접 연관
    * **amount**: 연관 자금 규모
    * **percentage**: 총 거래량 대비 비율
  </Accordion>

  <Accordion title="direct와 indirect의 차이점은 무엇인가요?">
    | 유형       | 의미                     | 위험 수준    |
    | :------- | :--------------------- | :------- |
    | direct   | 주소가 위험 단체와 직접 상호작용     | 더 높음     |
    | indirect | 주소가 중간 주소를 통해 간접적으로 연관 | 상대적으로 낮음 |

    **예시:**

    * `sanctioned entity + direct`: 주소가 제재 대상 주소에 직접 송금
    * `sanctioned entity + indirect`: 이 주소의 연관 주소가 이전에 제재 대상 주소와 상호작용

    Severe 수준 라벨(제재, 테러 자금 조달)을 포함하는 경우 간접 연관이라도 신중한 처리가 필요합니다.
  </Accordion>

  <Accordion title="Address Type에는 어떤 유형이 있나요?">
    | 주소 유형              | 설명          |
    | :----------------- | :---------- |
    | PRIVATE\_WALLET    | 개인 지갑 주소    |
    | EXCHANGE           | 중앙화 거래소 주소  |
    | CONTRACT           | 스마트 컨트랙트 주소 |
    | MINING\_POOL       | 마이닝 풀 주소    |
    | MERCHANT           | 가맹점 주소      |
    | PAYMENT\_PROCESSOR | 결제 처리업체     |

    주소 유형은 자금 흐름과 비즈니스 맥락을 이해하는 데 도움이 됩니다.
  </Accordion>

  <Accordion title="API로 Address Verification을 호출하는 방법은?">
    ```bash theme={null}
    curl -X POST "https://api.chainstream.io/v1/kya/address/verify" \
      -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "address": "So11111111111111111111111111111111111111112",
        "chain": "sol"
      }'
    ```

    **응답 예시:**

    ```json theme={null}
    {
      "address": "So11111111111111111111111111111111111111112",
      "risk": "Low",
      "status": "COMPLETE",
      "address_type": "PRIVATE_WALLET",
      "risk_exposures": [
        {
          "label": "sanctioned entity",
          "severity": "Severe",
          "type": "indirect",
          "amount": 372262.76,
          "percentage": 0.6
        },
        {
          "label": "bridge",
          "severity": "Info",
          "type": "indirect",
          "amount": 816082.22,
          "percentage": 1.3
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="KYT 탐지에는 얼마나 걸리나요?">
    | 작업             | 응답 시간        |
    | :------------- | :----------- |
    | 새 주소 첫 검증      | 보통 1\~5초     |
    | 캐시된 주소 쿼리      | \< 500ms     |
    | 복잡한 주소 (거래 다수) | 5\~10초 소요 가능 |

    상태가 `PENDING`이면 분석 중입니다. 나중에 재시도하여 전체 결과를 확인하세요.
  </Accordion>

  <Accordion title="KYT/KYA는 어떻게 과금되나요?">
    KYT/KYA API는 **플랜 Units를 소비하지 않습니다**. 별도의 KYT 계정 잔액(USD 기준)에서 차감됩니다.

    | 작업       | 비용       |
    | :------- | :------- |
    | 입금 위험 평가 | \$0.25/건 |
    | 출금 위험 평가 | \$0.25/건 |
    | 주소 등록    | \$1.25/건 |

    Dashboard → KYT Service에서 충전하세요.
  </Accordion>
</AccordionGroup>

***

## AI/MCP 관련

<AccordionGroup>
  <Accordion title="MCP란 무엇인가요?">
    MCP(Model Context Protocol)는 Anthropic이 제안한 프로토콜로, AI 모델이 외부 도구를 호출할 수 있게 합니다.

    ChainStream은 MCP Server를 제공하여 Claude 등의 AI가 온체인 데이터를 직접 조회할 수 있습니다.

    자세한 내용은 [MCP Server 문서](/ko/docs/ai-agents/mcp-server/introduction)를 참조하세요.
  </Accordion>

  <Accordion title="Claude Desktop에서 ChainStream을 사용하려면?">
    1. ChainStream MCP Server 설치
    2. Claude Desktop의 MCP 설정 구성
    3. Claude Desktop 재시작
    4. 대화 시작 — Claude가 자동으로 ChainStream을 호출하여 데이터 조회

    자세한 설정은 [Claude Integration 가이드](/ko/docs/ai-agents/mcp-server/setup)를 참조하세요.
  </Accordion>

  <Accordion title="AI가 거래를 실행할 수 있나요?">
    **현재 지원하지 않습니다.** ChainStream MCP Server는 읽기 작업만 제공합니다:

    * 토큰 가격 및 정보 조회
    * 지갑 잔고 및 거래 내역 조회
    * KYT/KYA 위험 평가 실행

    보안상의 이유로 자동 거래 실행, 송금 등 쓰기 작업은 지원하지 않습니다.
  </Accordion>

  <Accordion title="MCP 호출은 어떻게 과금되나요?">
    MCP 호출은 직접 API 호출과 동일하게 과금되며, 실제 호출된 API 유형에 따라 Units를 소비합니다.
  </Accordion>
</AccordionGroup>

***

## 고객 지원

<AccordionGroup>
  <Accordion title="기술 지원은 어떻게 받나요?">
    | 채널                                                          | 용도                     | 응답 시간   |
    | :---------------------------------------------------------- | :--------------------- | :------ |
    | 이메일 [support@chainstream.io](mailto:support@chainstream.io) | 일반 문의                  | 24시간 이내 |
    | Discord 커뮤니티                                                | 기술 토론, 사용법 질문          | 커뮤니티 지원 |
    | 전담 어카운트 매니저                                                 | Enterprise / Custom 고객 | 4시간 이내  |

    **문의 시 다음을 제공해 주세요:**

    * Client ID
    * 오류 메시지 및 재현 절차
  </Accordion>

  <Accordion title="문서 오류를 어떻게 보고하나요?">
    * **GitHub Issues:** 문서 이슈 제출
    * **이메일:** [docs@chainstream.io](mailto:docs@chainstream.io)

    문서 개선에 도움 주셔서 감사합니다!
  </Accordion>
</AccordionGroup>

***

## 답변을 찾지 못하셨나요?

<Card title="문의하기" icon="headset" href="mailto:support@chainstream.io">
  위 FAQ에서 답변을 찾지 못하셨다면, 기술 지원팀에 문의해 주세요.
</Card>