> ## Documentation Index
> Fetch the complete documentation index at: https://www.helius.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 인증

> Helius API 요청을 안전하고 효율적으로 인증하는 방법을 배웁니다

Helius API는 API 키를 사용하여 요청을 인증합니다. 모든 API 요청에는 신원과 권한을 확인하기 위해 API 키가 포함되어야 합니다.

<Warning>
  API 키는 Helius 계정에 대한 액세스를 허용하는 민감한 정보입니다. 클라이언트 사이드 코드, 공용 저장소 또는 브라우저에서 접근 가능한 영역에 절대 노출하지 마세요.
</Warning>

## 시작하기

### 1. API 키 생성하기

<Steps>
  <Step title="가입 또는 로그인">
    [Helius Dashboard](https://dashboard.helius.dev)에서 계정을 만들거나 기존 계정에 로그인합니다.
  </Step>

  <Step title="API 키로 이동">
    대시보드 사이드바에서 **API 키** 섹션으로 이동합니다.
  </Step>

  <Step title="새 키 생성">
    **새 API 키 생성**을 클릭하고 프로젝트에 대한 설명을 입력합니다 (예: "프로덕션 앱", "개발 환경").
  </Step>

  <Step title="키 복사 및 보관">
    API 키를 즉시 복사하여 안전하게 보관하세요. 이동한 후에는 다시 볼 수 없습니다.
  </Step>
</Steps>

### 2. API 키 사용하기

모든 요청에 API 키를 쿼리 매개변수로 포함시키세요.

<CodeGroup>
  ```bash cURL theme={"system"}
  curl "https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY" \
    -X POST \
    -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","id":1,"method":"getAccountInfo","params":["ACCOUNT_ADDRESS"]}'
  ```

  ```javascript JavaScript theme={"system"}
  const url = `https://mainnet.helius-rpc.com/?api-key=${YOUR_API_KEY}`;
  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: 1,
      method: 'getAccountInfo',
      params: ['ACCOUNT_ADDRESS']
    })
  });
  ```

  ```python Python theme={"system"}
  import requests

  url = f"https://mainnet.helius-rpc.com/?api-key={YOUR_API_KEY}"
  payload = {
      "jsonrpc": "2.0",
      "id": 1,
      "method": "getAccountInfo",
      "params": ["ACCOUNT_ADDRESS"]
  }
  response = requests.post(url, json=payload)
  ```
</CodeGroup>

## 시작하기 (에이전트용)

에이전트는 [Helius CLI](/docs/ko/agents/cli)를 사용하여 Helius 계정에 프로그래밍 방식으로 가입하고, 프로젝트를 생성하며, API 키를 생성할 수 있습니다.

자세한 지침은 다음을 읽어보세요: [https://dashboard.helius.dev/agents.md](https://dashboard.helius.dev/agents.md)

### Helius CLI 설치하기

<CodeGroup>
  ```bash theme={"system"}
  npm install -g helius-cli
  ```
</CodeGroup>

### 키페어 생성

<CodeGroup>
  ```bash theme={"system"}
  helius keygen
  ```
</CodeGroup>

### 생성된 지갑 자금 확보 (Autopay 전용)

호스팅된 결제 링크를 통해 지불할 경우 이 단계를 건너뜁니다 (`--pay` / `--resume`). 자동 결제를 위해 1 USDC와 0.001 SOL을 2단계에서 제공된 지갑 주소로 전송하세요.

### 가입 및 API 키 받기

<CodeGroup>
  ```bash theme={"system"}
  helius signup --email you@example.com --first-name Jane --last-name Doe --json
  ```
</CodeGroup>

## 보안 모범 사례

<CardGroup cols={2}>
  <Card title="환경 변수" icon="shield-check">
    API 키를 소스 코드가 아닌 환경 변수에 저장하세요.

    ```bash theme={"system"}
    export HELIUS_API_KEY="YOUR_API_KEY"
    ```
  </Card>

  <Card title="IP 제한" icon="globe">
    대시보드에서 특정 IP 주소 또는 범위에 대한 액세스를 제한하기 위해 API 키에 IP 제한을 설정하세요.
  </Card>

  <Card title="분리된 키" icon="key">
    개발, 스테이징 및 프로덕션 환경에 대해 다른 API 키를 사용하여 사용을 분리하고 보안을 강화하세요.
  </Card>

  <Card title="사용량 모니터링" icon="chart-line">
    대시보드에서 API 사용량을 정기적으로 확인하여 비정상적인 패턴이나 잠재적 보안 문제를 감지하세요.
  </Card>
</CardGroup>

### 비밀 관리

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={"system"}
    // Use environment variables
    const apiKey = process.env.HELIUS_API_KEY;

    // Or use a secrets manager
    const { SecretManagerServiceClient } = require('@google-cloud/secret-manager');
    const client = new SecretManagerServiceClient();

    async function getApiKey() {
      const [version] = await client.accessSecretVersion({
        name: 'projects/PROJECT_ID/secrets/helius-api-key/versions/latest',
      });
      return version.payload.data.toString();
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    import os
    from dotenv import load_dotenv

    # Load environment variables
    load_dotenv()
    api_key = os.getenv('HELIUS_API_KEY')

    # Or use AWS Secrets Manager
    import boto3

    def get_secret():
        client = boto3.client('secretsmanager')
        response = client.get_secret_value(SecretId='helius-api-key')
        return response['SecretString']
    ```
  </Tab>

  <Tab title="Docker">
    ```dockerfile theme={"system"}
    # In your Dockerfile
    ENV HELIUS_API_KEY=""

    # Or use Docker secrets
    RUN --mount=type=secret,id=helius_key \
        cat /run/secrets/helius_key > /app/api_key.txt
    ```
  </Tab>
</Tabs>

## 제한 및 사용량

<Note>
  제한은 구독 계획에 따라 다릅니다. 할당된 제한 내에서 유지되도록 [Helius 대시보드](https://dashboard.helius.dev)에서 사용량을 모니터링하세요.
</Note>

### 제한 이해하기

* **초당 요청 수**: 구독 등급에 따라 다름
* **월간 요청 할당량**: 청구 주기당 허용된 총 요청 수
* **버스트 허용량**: 기본 속도 제한을 초과하는 단기 스파이크 허용

### 제한 처리

<CodeGroup>
  ```javascript JavaScript theme={"system"}
  async function makeRequest(url, data) {
    try {
      const response = await fetch(url, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(data)
      });
      
      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After');
        console.log(`Rate limited. Retry after ${retryAfter} seconds`);
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        return makeRequest(url, data); // Retry
      }
      
      return response.json();
    } catch (error) {
      console.error('Request failed:', error);
      throw error;
    }
  }
  ```

  ```python Python theme={"system"}
  import time
  import requests

  def make_request(url, data):
      try:
          response = requests.post(url, json=data)
          
          if response.status_code == 429:
              retry_after = int(response.headers.get('Retry-After', 60))
              print(f"Rate limited. Waiting {retry_after} seconds...")
              time.sleep(retry_after)
              return make_request(url, data)  # Retry
          
          response.raise_for_status()
          return response.json()
      except requests.exceptions.RequestException as e:
          print(f"Request failed: {e}")
          raise
  ```
</CodeGroup>

## 문제 해결

<AccordionGroup>
  <Accordion title="잘못된 API 키 오류">
    **증상**: 401 Unauthorized 또는 "Invalid API Key" 오류

    **해결책**:

    * API 키가 정확한지 확인하고 재생성되지 않았는지 확인
    * API 키가 쿼리 매개변수로 포함되었는지 확인: `?api-key=YOUR_KEY`
    * API 키에 공백이나 잘못된 문자가 없는지 확인
    * API 키가 만료되거나 취소되지 않았는지 확인
  </Accordion>

  <Accordion title="요청 제한 초과">
    **증상**: 429 Too Many Requests 오류

    **해결책**:

    * 대시보드에서 현재 사용량 확인
    * 재시도 로직에 지수 백오프 구현
    * 더 높은 제한을 위한 계획 업그레이드 고려
    * 불필요한 호출을 줄이도록 요청 최적화
  </Accordion>

  <Accordion title="허용되지 않는 액세스">
    **증상**: 403 Forbidden 오류

    **해결책**:

    * IP 제한이 요청을 차단하지 않는지 확인
    * 구독이 해당 엔드포인트에 대한 액세스를 포함하는지 확인
    * API 키에 필요한 권한이 있는지 확인
  </Accordion>
</AccordionGroup>

## 다음 단계

<CardGroup cols={2}>
  <Card title="빠른 시작 가이드" icon="rocket" href="/docs/ko/quickstart">
    Helius로 첫 번째 API 호출 시작하기
  </Card>

  <Card title="API 참조" icon="book" href="/docs/ko/api-reference">
    사용 가능한 모든 엔드포인트 및 메서드 탐색하기
  </Card>

  <Card title="요청 제한" icon="credit-card" href="/docs/ko/billing/rate-limits">
    요청 제한 및 업그레이드 옵션 이해하기
  </Card>

  <Card title="대시보드" icon="chart-line" href="https://dashboard.helius.dev">
    API 사용량 모니터링 및 키 관리하기
  </Card>
</CardGroup>

## 지원

인증에 대한 도움이 필요하거나 API 키 관련 질문이 있나요?

<CardGroup cols={2}>
  <Card title="디스코드 커뮤니티" icon="discord" href="https://discord.com/invite/6GXdee3gBj">
    실시간 도움 및 커뮤니티 지원을 위한 디스코드 가입
  </Card>

  <Card title="이메일 지원" icon="envelope" href="mailto:support@helius.xyz">
    지원 팀에 직접 문의하기
  </Card>
</CardGroup>