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

> AI 에이전트를 위한 Helius TypeScript SDK의 완벽한 가이드입니다. DAS API, 트랜잭션, Helius Sender, 웹훅, WebSockets, 스테이킹, ZK 압축 및 프로그램 방식의 가입을 위한 타입 안전 메서드를 제공합니다.

[Helius TypeScript SDK](https://github.com/helius-labs/helius-sdk)는 모든 Helius API에 대한 타입 안전 메서드를 제공하여 에이전트가 Solana와 상호 작용하는 가장 빠른 방법을 제공합니다.

* **패키지**: `helius-sdk` (npm / pnpm / yarn)
* **버전**: 2.x (`@solana/kit` 사용, not `@solana/web3.js`)
* **런타임**: 모든 JavaScript 런타임 — 브라우저, Deno, Bun, edge 런타임 (Cloudflare Workers, Vercel Edge), Node.js 20+
* **TypeScript**: 5.8+ (전체 타입 정의 포함)
* **라이선스**: ISC

## 설치

```bash theme={"system"}
npm install helius-sdk
```

## 빠른 시작

```typescript theme={"system"}
import { createHelius } from "helius-sdk";

const helius = createHelius({
  apiKey: "YOUR_API_KEY",
  network: "mainnet", // or "devnet"
});

// Get all NFTs and tokens owned by a wallet
const assets = await helius.getAssetsByOwner({
  ownerAddress: "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY",
  page: 1,
  limit: 50,
});

// Get transaction history (with token account activity)
const txs = await helius.getTransactionsForAddress([
  "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY",
  { limit: 100, transactionDetails: "full", filters: { tokenAccounts: "balanceChanged" } },
]);

// Send a transaction via Helius Sender (ultra-low latency)
const sig = await helius.tx.sendTransactionWithSender({
  instructions: [transferInstruction],
  signers: [walletSigner],
  region: "US_EAST",
});
```

## 클라이언트 옵션

```typescript theme={"system"}
const helius = createHelius({
  apiKey: "YOUR_API_KEY",       // Required for webhooks, enhanced txs, wallet API
  network: "mainnet",           // "mainnet" (default) or "devnet"
  baseUrl: "https://custom..",  // Override RPC URL (optional)
  rebateAddress: "wallet",      // Wallet for RPC rebates (optional)
  userAgent: "my-agent/1.0",   // Sent as X-Helius-Client header (optional)
});
```

## 네임스페이스

모든 메서드는 `helius` 클라이언트를 통해 접근할 수 있습니다. DAS API 메서드와 표준 Solana RPC 메서드는 직접 `helius.*`에서 사용할 수 있습니다. 다른 기능은 네임스페이스로 구성됩니다:

| 네임스페이스     | 접근                                                                    | 목적                                 |
| ---------- | --------------------------------------------------------------------- | ---------------------------------- |
| DAS API    | `helius.getAsset()`, `helius.getAssetsByOwner()`, 등                   | NFT, 토큰, 압축 자산 조회                  |
| RPC V2     | `helius.getTransactionsForAddress()`, `helius.getProgramAccountsV2()` | 페이지네이션 및 필터가 포함된 향상된 RPC           |
| 트랜잭션       | `helius.tx.*`                                                         | 스마트 트랜잭션 및 Helius Sender           |
| 향상된        | `helius.enhanced.*`                                                   | 트랜잭션을 사람이 읽을 수 있는 형식으로 파싱          |
| 웹훅         | `helius.webhooks.*`                                                   | 웹훅 구독 생성 및 관리                      |
| WebSockets | `helius.ws.*`                                                         | 실시간 블록체인 데이터 스트림                   |
| 스테이킹       | `helius.stake.*`                                                      | Helius 검증자에게 SOL 스테이킹              |
| ZK 압축      | `helius.zk.*`                                                         | 압축 계정 및 증명                         |
| 지갑 API     | `helius.wallet.*`                                                     | 잔액, 기록, 식별 조회                      |
| 표준 RPC     | `helius.getBalance()`, `helius.getSlot()`, 등                          | 프록시를 통해 모든 표준 Solana RPC 메서드       |
| Raw RPC    | `helius.raw`                                                          | 기본 `@solana/kit` Rpc 클라이언트에 직접 액세스 |
| 인증         | `import { makeAuthClient } from "helius-sdk/auth/client"`             | 에이전트 가입 및 API 키 관리 (독립형 가져오기)      |

## 프로그래밍 방식의 가입 (인증 모듈)

인증 모듈은 독립형 가져오기입니다 — 주 `HeliusClient`에 있지 않습니다. 프로그램 방식의 에이전트 가입 흐름에 사용하세요.

```typescript theme={"system"}
import { makeAuthClient } from "helius-sdk/auth/client";

const auth = makeAuthClient();

// Hosted-link signup (returns a paymentUrl the user opens in a browser):
const link = await auth.signup({
  secretKey: keypair.secretKey,
  plan: "agent",
  email: "you@example.com",
  firstName: "Ada",
  lastName: "Lovelace",
});
// link: { kind: "payment_required", jwt, refId, walletAddress, paymentLink: { paymentUrl, ... } }

// Or pay USDC directly from the local keypair and provision in one call:
const result = await auth.signupAndPay({
  secretKey: keypair.secretKey,
  plan: "agent",
  email: "you@example.com",
  firstName: "Ada",
  lastName: "Lovelace",
});
// result.kind: "completed" | "pending" | "expired" | "failed" | "already_subscribed" | "upgrade_required"
// On "completed": result has { jwt, walletAddress, projectId, apiKey, endpoints, txSignature }
```

## 심층 학습

<CardGroup cols={2}>
  <Card title="모범 사례" icon="lightbulb" href="/docs/ko/agents/typescript-sdk/best-practices">
    권장 패턴, 페이지네이션, 일반적인 실수 및 오류 처리
  </Card>

  <Card title="API 참조" icon="book" href="/docs/ko/agents/typescript-sdk/api-reference">
    모든 네임스페이스에 대한 전체 메서드 목록
  </Card>
</CardGroup>

## 리소스

<CardGroup cols={2}>
  <Card title="GitHub 저장소" icon="github" href="https://github.com/helius-labs/helius-sdk">
    소스 코드, 예제 및 문제 추적
  </Card>

  <Card title="코드 예제" icon="code" href="https://github.com/helius-labs/helius-sdk/tree/main/examples">
    네임스페이스별로 정리된 모든 메서드에 대한 동작 예제
  </Card>

  <Card title="SDK API 문서 (TypeDoc)" icon="book" href="https://helius-labs.github.io/helius-sdk/">
    소스에서 생성된 전체 API 문서
  </Card>

  <Card title="마이그레이션 가이드 (1.x to 2.x)" icon="arrow-right" href="https://github.com/helius-labs/helius-sdk/blob/main/MIGRATION.md">
    @solana/web3.js에서 @solana/kit로 업그레이드
  </Card>
</CardGroup>