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

# Wallet API 개요 (베타)

> Wallet API로 Solana 지갑 데이터를 쿼리하세요. 잔액, 거래 내역, 전송, 신원 정보, 자금 출처를 단일 요청으로 가져옵니다.

<Note>
  Wallet API는 베타 버전입니다. 엔드포인트와 응답 형식이 변경될 수 있습니다.
</Note>

## Wallet API란 무엇인가요?

Wallet API는 Solana 지갑 데이터(잔액, 거래 내역, 토큰 전송, 신원 확인, 과거 잔액, 자금 출처)를 쿼리하기 위한 고수준 REST 엔드포인트를 제공합니다. 여러 RPC 호출을 통해 원시 블록체인 데이터를 분석하지 않고, 구조화된 인간이 읽을 수 있는 정보와 USD 가격을 단일 요청으로 얻을 수 있습니다.

이 API는 지갑, 포트폴리오 추적기, 탐색기, 결제 처리기, 세금 도구, 규제 준수 및 AML 시스템을 위해 구축되었습니다. 모든 엔드포인트는 기본 URL `https://api.helius.xyz`을 공유하며, 인간이 읽을 수 있는 단위로 금액을 반환합니다(라포트 변환 필요 없음).

## 왜 지갑 데이터에 Helius를 사용해야 하나요?

<CardGroup cols={2}>
  <Card title="하나의 REST 호출" icon="bolt">
    원시 RPC 응답을 연결할 필요 없이 구조화된 잔액, 내역 및 전송을 제공
  </Card>

  <Card title="USD 가격 내장" icon="dollar-sign">
    토큰 잔액에는 DAS에서 제공하는 USD 값과 포트폴리오 총액이 포함됩니다.
  </Card>

  <Card title="신원 확인" icon="address-card">
    32,500개 이상의 라벨링된 계정과 프로그램, 21.5M+ 범주 태그.
  </Card>

  <Card title="인간이 읽을 수 있는 출력" icon="book-open">
    원시 라포트 및 명령 대신 명확하고 소수점이 조정된 데이터.
  </Card>
</CardGroup>

## 주요 엔드포인트

<CardGroup cols={2}>
  <Card title="지갑 신원" icon="address-card" href="/docs/ko/wallet-api/identity">
    주소 또는 SNS/ANS 도메인으로 알려진 지갑 식별 — 거래소, 프로토콜,
    기관.
  </Card>

  <Card title="지갑 잔액" icon="scale-balanced" href="/docs/ko/wallet-api/balances">
    USD 값, 로고, 메타데이터를 포함한 모든 토큰 및 NFT 잔액.
  </Card>

  <Card title="과거 잔액" icon="clock" href="/docs/ko/wallet-api/balance-at">
    과거 타임스탬프, 날짜, 슬롯에 따른 토큰 또는 SOL 잔액.
  </Card>

  <Card title="지갑 내역" icon="clock-rotate-left" href="/docs/ko/wallet-api/history">
    각 거래에 대한 잔액 변화를 포함한 전체 거래 내역.
  </Card>

  <Card title="토큰 전송" icon="arrow-right-arrow-left" href="/docs/ko/wallet-api/transfers">
    발신자/수신자 정보를 포함한 모든 입출금 전송.
  </Card>

  <Card title="자금 출처" icon="money-bill-transfer" href="/docs/ko/wallet-api/funded-by">
    지갑의 원래 자금 출처를 첫 번째 입력 SOL까지 추적.
  </Card>
</CardGroup>

## 어떤 엔드포인트를 사용해야 하나요?

| 필요에 따라                   | 이 엔드포인트 사용                         | 반환값                           |
| ------------------------ | ---------------------------------- | ----------------------------- |
| 지갑이 누구인지 (거래소, 프로토콜, 라벨) | [신원확인](/docs/ko/wallet-api/identity)    | 알려진 주소의 이름, 범주 및 태그           |
| 지갑의 현재 포트폴리오             | [잔액](/docs/ko/wallet-api/balances)      | USD 값을 포함한 모든 토큰 및 NFT        |
| 과거 특정 시점의 잔액             | [과거 잔액](/docs/ko/wallet-api/balance-at) | 타임스탬프/날짜/슬롯 기준 한 토큰 또는 SOL 잔액 |
| 전체 거래 활동                 | [역사](/docs/ko/wallet-api/history)       | 거래당 잔액 변화를 포함한 파싱된 거래         |
| 전송된/수신된 전송만              | [전송](/docs/ko/wallet-api/transfers)     | 거래 상대방과 방향을 포함한 전송 수준 뷰       |
| 지갑의 자금 출처                | [자금 출처](/docs/ko/wallet-api/funded-by)  | 첫 번째 입력 SOL 전송 및 발신자          |

간단한 경로 참조 (기본 URL `https://api.helius.xyz`):

* `GET /v1/wallet/{wallet}/identity` — 주소 또는 SNS/ANS 도메인으로 지갑 신원 가져오기
* `POST /v1/wallet/batch-identity` — 최대 100개 주소 및/또는 도메인에 대한 배치 신원 검색
* `GET /v1/wallet/{wallet}/balances` — 모든 토큰 및 NFT 잔액 가져오기
* `GET /v1/wallet/{wallet}/balance-at` — 과거 타임스탬프, 날짜, 슬롯의 토큰 또는 SOL 잔액 가져오기
* `GET /v1/wallet/{wallet}/history` — 잔액 변화를 포함한 거래 내역 가져오기
* `GET /v1/wallet/{wallet}/transfers` — 모든 토큰 전송 활동 가져오기
* `GET /v1/wallet/{wallet}/funded-by` — 원래 자금 출처 찾기

## 인증

모든 Wallet API 요청에는 API 키가 필요합니다. 쿼리 매개변수나 헤더로 전달할 수 있습니다:

<Tabs>
  <Tab title="쿼리 매개변수">
    ```bash theme={"system"}
    curl "https://api.helius.xyz/v1/wallet/{wallet}/balances?api-key=YOUR_API_KEY"
    ```
  </Tab>

  <Tab title="헤더">
    ```bash theme={"system"}
    curl "https://api.helius.xyz/v1/wallet/{wallet}/balances" \
      -H "X-Api-Key: YOUR_API_KEY"
    ```
  </Tab>
</Tabs>

## 플랜 요구 사항

신원 및 자금 출처 엔드포인트에는 유료 플랜이 필요합니다. 무료 플랜에서는 이러한 엔드포인트 요청 시 `403 Forbidden`가 반환됩니다. 다른 모든 엔드포인트는 무료 플랜을 포함하여 모든 플랜에서 열려 있습니다.

| 엔드포인트                                | 무료 플랜             |
| ------------------------------------ | ----------------- |
| `GET /v1/wallet/{wallet}/identity`   | `403` — 유료 플랜만 가능 |
| `POST /v1/wallet/batch-identity`     | `403` — 유료 플랜만 가능 |
| `GET /v1/wallet/{wallet}/funded-by`  | `403` — 유료 플랜만 가능 |
| `GET /v1/wallet/{wallet}/balances`   | 사용 가능             |
| `GET /v1/wallet/{wallet}/balance-at` | 사용 가능             |
| `GET /v1/wallet/{wallet}/history`    | 사용 가능             |
| `GET /v1/wallet/{wallet}/transfers`  | 사용 가능             |

유료 티어는 게이트 엔드포인트를 잠금 해제합니다 — 개발자, 비즈니스 및 그보다 높은 모든 티어(엔터프라이즈 등). 신원 및 자금 출처 조회를 활성화하려면, [대시보드에서 플랜을 업그레이드하세요](https://dashboard.helius.dev).

## 금액 및 단위

Wallet API는 원시 Solana 데이터에 대한 고수준 추상화입니다. 응답의 모든 `amount` 필드는 **인간이 읽을 수 있는** 형태로 제공됩니다 — 이미 토큰의 `decimals`으로 나누어져 있어 어떤 변환도 필요하지 않습니다. 원시 Solana RPC 호출은 라포트(가장 작은 단위, 10⁻⁹ SOL)로 값을 반환하지만, Wallet API는 그렇지 않습니다. `"amount": 1.5`은 1.5 SOL을 의미하며, 1.5 라포트가 아닙니다.

정확한 산술이 필요한 경우 일부 엔드포인트는 `amountRaw`를 노출합니다: 정수로 직렬화된 문자열로 부동 소수점 정밀도 손실을 방지합니다. 변환 공식은 다음과 같습니다:

`amount = parseInt(amountRaw) / 10**decimals`

| 엔드포인트                          | 인간이 읽을 수 있는 `amount`      | 원시 `amountRaw` 문자열 |
| ------------------------------ | ------------------------- | ------------------ |
| **Balances**                   | `balance` 필드              | 사용 불가              |
| **Balance-at**                 | `balance` 필드 (소수 **문자열**) | `balanceRaw` 필드    |
| **Funded-by**                  | `amount` 필드               | `amountRaw` 필드     |
| **Transfers**                  | `amount` 필드               | `amountRaw` 필드     |
| **History** (`balanceChanges`) | `amount` 필드               | 사용 불가              |

표시에 `amount`를 사용하세요. 정확한 정수 산술이 필요한 온체인 명령이나 다른 시스템에 값을 전달할 때는 `amountRaw`를 사용하세요.

## 시작하기

<Steps>
  <Step title="API 키를 받으세요">
    [dashboard.helius.dev](https://dashboard.helius.dev)에 가입하여 API 키를 받으세요.
  </Step>

  <Step title="엔드포인트를 선택하세요">
    위 표를 사용하여 귀하의 사용 사례에 맞는 엔드포인트를 선택하세요.
  </Step>

  <Step title="첫 요청을 만드세요">
    간단한 잔액 조회부터 시작하세요:

    ```bash theme={"system"}
    curl "https://api.helius.xyz/v1/wallet/86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY/balances?api-key=YOUR_API_KEY"
    ```
  </Step>

  <Step title="응답 처리">
    JSON 응답을 파싱하고 애플리케이션에서 데이터를 표시하세요.
  </Step>
</Steps>

## 다음 단계

<CardGroup cols={3}>
  <Card title="데이터 가져오기" icon="database" href="/docs/ko/getting-data">
    Helius에서 Solana 데이터를 쿼리하는 모든 방법을 탐색하세요.
  </Card>

  <Card title="API 참조" icon="code" href="/docs/ko/api-reference/wallet-api">
    모든 Wallet API 엔드포인트의 요청 및 응답 스키마.
  </Card>

  <Card title="지원 문의" icon="headset" href="/docs/ko/support/contact-support">
    Discord, 채팅 또는 이메일을 통해 도움 받기.
  </Card>
</CardGroup>