> ## 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 for Agents

> "Helius와 함께 Solana에서 AI 에이전트를 구축하기 위한 모든 것: 프로그래밍 방식의 등록, API 액세스, SDK, MCP 통합, 권장 워크플로우."

Helius는 Solana에서 AI 에이전트를 구축하기 위한 최상의 지원을 제공합니다. 프로그래밍 방식의 계정 생성부터 실시간 데이터 스트리밍까지, 에이전트는 수동 개입 없이 Helius의 모든 기능에 접근할 수 있습니다.

* [Helius MCP](/docs/ko/agents/mcp) — 블록체인 쿼리, 트랜잭션 전송, 스트리밍 등을 다루는 10개의 라우팅된 도구
* [Claude Code Plugin](/docs/ko/agents/claude-code-plugin) — 암호화폐 회사에서 제공하는 최초이자 현재 유일한 공식 Claude Code 플러그인. 한 번의 설치: MCP 서버 + 스킬 + 참조 파일
* [Skills](/docs/ko/agents/skills/overview) — Claude를 위한 전문가 지침 세트: [Build](/docs/ko/agents/skills/build), [Phantom](/docs/ko/agents/skills/phantom), [Jupiter](/docs/ko/agents/skills/jupiter), [DFlow](/docs/ko/agents/skills/dflow), [OKX](/docs/ko/agents/skills/okx), [SVM](/docs/ko/agents/skills/svm)
* [TypeScript SDK](/docs/ko/agents/typescript-sdk) — 모든 Helius API에 대한 타입 안전 메소드
* [Rust SDK](/docs/ko/agents/rust-sdk) — Helius API를 위한 고성능 Rust SDK
* [Helius CLI](/docs/ko/agents/cli) — 계정 관리 및 셸 스크립팅

<Note>
  이 섹션의 기계 판독용 버전은 AI 에이전트 소비를 위해 [agents/llms.txt](https://www.helius.dev/docs/agents/llms.txt)에서 제공됩니다.
</Note>

## MCP vs CLI

[Helius MCP 서버](/docs/ko/agents/mcp)는 AI 에이전트가 Helius와 상호작용하는 권장 방법입니다. 이는 AI에게 Solana에 대한 직접적이고 구조적인 접근을 제공하는 10개의 라우팅된 도구를 제공합니다 — 셸 명령 없음, 출력 파싱 없음, 수동 API 호출 없음.

|            | [MCP](/docs/ko/agents/mcp)                                                                                             | [CLI](/docs/ko/agents/cli)                |
| ---------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| **최적의 대상** | Claude Code, Cursor, Claude Desktop 및 모든 MCP 호환 도구의 AI 에이전트                                                       | 셸 스크립트, CI/CD 파이프라인, 터미널 워크플로우       |
| **인터페이스**  | 타입이 지정된 입력/출력과 구조화된 도구 호출                                                                                         | `--json` 출력과의 명령줄                    |
| **기능**     | 블록체인 쿼리, 트랜잭션, 웹훅, 스트리밍, 지갑 분석, 문서 및 등록을 다루는 10개의 라우팅된 도구 (`heliusWallet`, `heliusAsset`, `heliusTransaction`, …) | 구성 관리 및 대화형 흐름을 포함하는 95+ 명령: 동일한 기능  |
| **계정 설정**  | 내장: `heliusAccount` 작업 `generateKeypair` → `signup` (링크 또는 자동 결제) — 외부 도구 필요 없음                                   | `helius keygen` → `helius signup`    |
| **사용 시점**  | 모든 AI 에이전트의 기본 선택                                                                                                 | 셸 수준 자동화가 필요하거나 MCP 호환 도구를 사용하지 않을 때 |

<Tip>
  **MCP로 시작하세요.** AI 도구가 MCP(Claude Code, Cursor, Claude Desktop 등)를 지원하는 경우 [MCP 서버](/docs/ko/agents/mcp)나 [Claude Code Plugin](/docs/ko/agents/claude-code-plugin)을 사용하세요. CLI는 셸 스크립팅 및 CI/CD에 유용하지만, AI 중심 워크플로우에는 MCP가 더 원활한 경험을 제공합니다 — AI가 셸 명령 생성을 대신해 도구를 직접 호출합니다.
</Tip>

## 빠른 시작: 에이전트 가입

에이전트는 [Helius CLI](/docs/ko/agents/cli)를 사용하여 네 단계로 Helius 계정을 만들고 API 키를 받을 수 있습니다:

```bash theme={"system"}
npm install -g helius-cli    # Install CLI
helius keygen                 # Generate keypair
# (Autopay only) Fund wallet with 1 USDC + ~0.001 SOL — skip if paying via the hosted link
helius signup --email you@example.com --first-name Jane --last-name Doe --json          # Get API key (JSON output)
```

성공하면 에이전트는 API 키, RPC 엔드포인트 및 1,000,000 크레딧을 받게 됩니다. 자세한 내용은 [CLI 전체 가이드](/docs/ko/agents/cli)를 참조하세요.

## 인증

모든 Helius API 요청에는 쿼리 매개변수로 전달되는 API 키가 필요합니다:

```
?api-key=YOUR_API_KEY
```

이를 모든 RPC 또는 API 엔드포인트에 추가하십시오. 예를 들어: `https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY`

[Helius Dashboard](https://dashboard.helius.dev)에서 또는 [Helius CLI](/docs/ko/agents/cli)를 통해 프로그래밍 방식으로 API 키를 얻으십시오.

<Tip>
  **더 낮은 대기 시간을 위해 Gatekeeper를 사용하세요** — [Gatekeeper (Beta)](/docs/ko/gatekeeper/overview)는 중요한 경로에서 Cloudflare를 제거하여 응답 시간을 수십에서 수백 밀리초로 줄입니다. 동일한 API 키, 동일한 메서드 — 단순히 엔드포인트를 교체하세요:

  ```
  https://beta.helius-rpc.com/?api-key=YOUR_API_KEY
  wss://beta.helius-rpc.com/?api-key=YOUR_API_KEY
  ```

  모든 RPC, DAS, WebSocket, ZK Compression, Priority Fee 및 Enhanced Transaction 메서드를 지원합니다. 자세한 내용은 [마이그레이션 가이드](/docs/ko/gatekeeper/migration-guide)를 참조하세요.
</Tip>

## Helius 전용 API 가이드

표준 Solana RPC 메서드를 체인으로 연결하는 대신 다음의 Helius 최적화 API를 사용하십시오:

| 대신...                                        | 이걸 사용하세요                                                                                                             | 이유                                                    |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `getSignaturesForAddress` + `getTransaction` | [`getTransactionsForAddress`](/docs/ko/rpc/gettransactionsforaddress)                                                     | 하나의 호출로 토큰 계정 데이터를 포함한 전체 트랜잭션 기록을 반환                 |
| `getTokenAccountsByOwner`                    | [`getAssetsByOwner`](/docs/ko/api-reference/das/getassetsbyowner) (DAS API)                                               | 단순한 로우 계정이 아닌 풍부한 메타데이터 반환                            |
| `getRecentPrioritizationFees`                | [`getPriorityFeeEstimate`](/docs/ko/api-reference/priority-fee/getpriorityfeeestimate)                                    | 사전 계산된 최적 수수료, 수작업 계산 필요 없음                           |
| `getSignaturesForAddress` (cNFT의 경우)         | [`getSignaturesForAsset`](/docs/ko/api-reference/das/getsignaturesforasset) (DAS API)                                     | 표준 RPC는 압축된 NFT에 대해 작동하지 않음                           |
| `getProgramAccounts` (NFT 검색용)               | [`searchAssets`](/docs/ko/api-reference/das/searchassets) 또는 [`getAssetsByGroup`](/docs/ko/api-reference/das/getassetsbygroup) | 더 빠르고, 저렴하며, 인덱싱된 데이터                                 |
| 실시간 데이터에 대한 폴링                               | [LaserStream WebSocket](/docs/ko/rpc/websocket) 또는 [LaserStream gRPC](/docs/ko/laserstream)                                    | 더 낮은 대기 시간, 더 효율적                                     |
| 표준 `sendTransaction`                         | [Helius Sender](/docs/ko/sending-transactions/sender)                                                                     | 멀티 패스 라우팅 (Helius, Jito, Harmonic, Rakurai 등), 높은 착륙률 |

## 권장 워크플로우

| 빌드 중...    | 사용할 Helius 제품                                                                                                                                                                                    |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 거래 봇       | [Gatekeeper](/docs/ko/gatekeeper/overview) (최저 대기 시간 RPC) + [Sender](/docs/ko/sending-transactions/sender) (빠른 tx 제출) + [Priority Fee API](/docs/ko/priority-fee-api) + [LaserStream](/docs/ko/laserstream) (실시간 가격) |
| 지갑 앱       | [DAS API](/docs/ko/das-api) (`getAssetsByOwner`) + [`getTransactionsForAddress`](/docs/ko/rpc/gettransactionsforaddress) (완전한 기록)                                                                          |
| NFT 마켓플레이스 | [DAS API](/docs/ko/das-api) (`searchAssets`, `getAssetsByGroup`) + [Webhooks](/docs/ko/webhooks) (판매/리스트 추적)                                                                                               |
| 토큰 스나이퍼    | [Gatekeeper](/docs/ko/gatekeeper/overview) (에지 라우트 RPC) + [LaserStream gRPC](/docs/ko/laserstream) (최저 대기 시간) + [Sender](/docs/ko/sending-transactions/sender) (스테이킹된 연결)                                       |
| 포트폴리오 추적기  | [DAS API](/docs/ko/das-api) (`getAssetsByOwner` 와 `showFungible`) + [Enhanced Transactions](/docs/ko/enhanced-transactions/overview)                                                                       |
| 지갑 모니터     | 실시간 알림을 위한 [LaserStream WebSocket](/docs/ko/rpc/websocket) 또는 [Webhooks](/docs/ko/webhooks)                                                                                                                |
| 분석 대시보드    | [Enhanced Transactions API](/docs/ko/enhanced-transactions/overview) + [`getTransactionsForAddress`](/docs/ko/rpc/gettransactionsforaddress)                                                               |
| 에어드롭 도구    | [AirShip](https://airship.helius.dev) (ZK 압축으로 95% 저렴)                                                                                                                                           |

## 속도 제한 빠른 참조

속도 제한은 [계획](/docs/ko/billing/plans)에 따라 다릅니다. 에이전트는 1,000,000 크레딧으로 에이전트 등급에서 시작합니다. 에이전트 등급은 남용을 방지하기 위해 \$1의 결제가 필요합니다.

| 계획   | 가격      | 월별 크레딧 | RPC 속도 제한 | DAS & Enhanced API |
| ---- | ------- | ------ | --------- | ------------------ |
| 에이전트 | \$1 가입  | 1M     | 10 req/s  | 2 req/s            |
| 개발자  | \$49/월  | 10M    | 50 req/s  | 10 req/s           |
| 사업   | \$499/월 | 100M   | 200 req/s | 50 req/s           |
| 전문   | \$999/월 | 200M   | 500 req/s | 100 req/s          |

각 API별 자세한 속도 제한은 [속도 제한](/docs/ko/billing/rate-limits)을 참조하세요.

## API 호출당 크레딧

| API                         | 크레딧 | 참고 사항                                        |
| --------------------------- | --- | -------------------------------------------- |
| 표준 RPC 호출                   | 1   | 대부분의 Solana RPC 메서드                          |
| `getProgramAccounts`        | 10  | 가능한 경우 DAS API 대신 사용                         |
| DAS API                     | 10  | 모든 DAS 엔드포인트                                 |
| Enhanced Transactions       | 100 | 구문 분석된 트랜잭션 데이터                              |
| `getTransactionsForAddress` | 10+ | 전체 트랜잭션은 100개 반환당 10크레딧 비용; 서명만 응답은 10크레딧 정액 |
| `getTransfersByAddress`     | 10  | 개발자+ 계획에만 해당                                 |
| 지갑 API                      | 100 | 모든 지갑 API 엔드포인트                              |
| Priority Fee API            | 1   | 수수료 추정                                       |
| Sender                      | 0   | 모든 계획에서 무료                                   |
| 웹훅 이벤트                      | 1   | 전달된 이벤트당                                     |
| 웹훅 관리                       | 100 | 생성, 편집, 삭제                                   |

전체 내용은 [크레딧](/docs/ko/billing/credits)을 참조하세요.

## 재시도 및 오류 처리

### HTTP 상태 코드

| 코드  | 의미      | 조치             |
| --- | ------- | -------------- |
| 200 | 성공      | 응답 처리          |
| 400 | 잘못된 요청  | 요청 매개변수 수정     |
| 401 | 인증되지 않음 | API 키 확인       |
| 429 | 속도 제한됨  | 백오프 후 재시도      |
| 5xx | 서버 오류   | 지수 백오프와 함께 재시도 |

### 재시도 패턴

```typescript theme={"system"}
async function heliusRequest(url: string, data: object, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data),
    });

    if (response.ok) return response.json();

    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After');
      const delay = retryAfter ? parseInt(retryAfter) * 1000 : Math.pow(2, attempt) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
      continue;
    }

    if (response.status >= 500) {
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
      continue;
    }

    throw new Error(`Request failed: ${response.status} ${await response.text()}`);
  }
  throw new Error('Max retries exceeded');
}
```

### 크레딧 사용량 모니터링

```bash theme={"system"}
helius usage --json
```

## 빠른 참조

* **메인넷 RPC**: `https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY`
* **메인넷 RPC (Gatekeeper Beta)**: `https://beta.helius-rpc.com/?api-key=YOUR_API_KEY`
* **Devnet RPC**: `https://devnet.helius-rpc.com/?api-key=YOUR_API_KEY`
* **메인넷 WSS**: `wss://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY`
* **메인넷 WSS (Gatekeeper Beta)**: `wss://beta.helius-rpc.com/?api-key=YOUR_API_KEY`
* **Devnet WSS**: `wss://devnet.helius-rpc.com/?api-key=YOUR_API_KEY`
* **솔더 엔드포인트**: `https://sender.helius-rpc.com/fast`
* **MCP 서버**: `https://www.helius.dev/docs/mcp`
* **대시보드**: [dashboard.helius.dev](https://dashboard.helius.dev)
* **상태**: [helius.statuspage.io](https://helius.statuspage.io)