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

# 지갑 잔액 확인 방법

> 모든 Solana 지갑의 모든 토큰 및 NFT 잔액을 USD 값, 로고 및 메타데이터와 함께 검색합니다. 포트폴리오 추적을 쉽게 하기 위해 가치 순으로 정렬됩니다.

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

## 개요

Wallet Balances 엔드포인트는 Solana 지갑의 모든 토큰 및 NFT 보유량 — SOL, SPL 토큰, Token-2022 및 NFT — 를 USD 가격, 로고 및 메타데이터와 함께 검색합니다. 결과는 내림차순으로 USD 가치에 따라 정렬됩니다: 가격 데이터가 있는 토큰이 먼저 나타나고, 가격이 없는 토큰이 뒤따릅니다.

엔드포인트는 요청당 최대 100개의 토큰을 반환하므로 페이지 매김은 수동입니다. 추가 페이지를 가져오려면 `page` 매개변수를 사용하고 더 많은 결과가 있을 때는 `pagination.hasMore`를 읽으십시오. 각 요청은 하나의 API 호출이며 100 크레딧이 소요됩니다.

<Note>USD 가격은 DAS에서 소스하며 시가 총액 상위 10,000개의 토큰을 대상으로 매시간 업데이트됩니다. 지원되지 않는 토큰은 `pricePerToken` 및 `usdValue`가 `null`입니다. 가격은 추정치이며 실시간 시장 가격이 아닙니다.</Note>

## 언제 사용할지

Wallet Balances API가 필요한 경우:

* **포트폴리오 보유 내역 표시**: 사용자의 전체 토큰 및 NFT 보유 내역을 보여줍니다.
* **USD 값 계산**: 매시간 업데이트되는 가격으로 포트폴리오 평가를 수행합니다.
* **지갑 UI 구축**: 지갑 대시보드와 자산 목록에 힘을 실어줍니다.
* **토큰 보유 추적**: 여러 지갑에서 특정 토큰 잔액을 모니터링합니다.
* **포트폴리오 분석**: 보유 분포 및 집중도를 분석합니다.
* **세금 보고**: 세금 목적으로 보유 내역 스냅샷을 생성합니다.

## 빠른 시작

### 기본 잔액 쿼리

지갑의 모든 토큰 잔액을 USD 값과 함께 가져옵니다:

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={"system"}
    const getWalletBalances = async (address) => {
      const url = `https://api.helius.xyz/v1/wallet/${address}/balances?api-key=YOUR_API_KEY`;

      const response = await fetch(url);
      if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
      }

      const data = await response.json();

      const solBalance = data.balances[0]; // SOL is always first when showNative=true
      console.log(`SOL Balance: ${solBalance.balance} SOL ($${solBalance.usdValue})`);
      console.log(`Page ${data.pagination.page} Total Value: $${data.totalUsdValue}`);
      console.log(`Token Count (this page): ${data.balances.length}`);

      // Display top holdings
      data.balances.slice(0, 5).forEach(token => {
        console.log(`${token.symbol}: ${token.balance} ($${token.usdValue || 'N/A'})`);
      });

      return data;
    };

    getWalletBalances("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY");
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    import requests

    def get_wallet_balances(address: str):
        url = f"https://api.helius.xyz/v1/wallet/{address}/balances"
        headers = {"X-Api-Key": "YOUR_API_KEY"}

        response = requests.get(url, headers=headers)
        response.raise_for_status()

        data = response.json()

        sol_balance = data['balances'][0]  # SOL is always first when showNative=true
        print(f"SOL Balance: {sol_balance['balance']} SOL (${sol_balance['usdValue']})")
        print(f"Page {data['pagination']['page']} Total Value: ${data['totalUsdValue']}")
        print(f"Token Count (this page): {len(data['balances'])}")

        # Display top holdings
        for token in data['balances'][:5]:
            usd_value = token.get('usdValue', 'N/A')
            print(f"{token['symbol']}: {token['balance']} (${usd_value})")

        return data

    get_wallet_balances("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY")
    ```
  </Tab>

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

### NFT 결과 포함

`showNfts=true`를 사용하여 단일 요청으로 토큰과 NFT를 모두 가져옵니다:

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={"system"}
    const getWalletWithNfts = async (address) => {
      const url = `https://api.helius.xyz/v1/wallet/${address}/balances?api-key=YOUR_API_KEY&showNfts=true`;

      const response = await fetch(url);
      const data = await response.json();

      console.log(`Tokens: ${data.balances.length}`);
      console.log(`NFTs: ${data.nfts?.length || 0}`);

      // Display NFTs
      data.nfts?.forEach(nft => {
        console.log(`NFT: ${nft.name || 'Unnamed'} (${nft.collectionName || 'Unknown Collection'})`);
      });

      return data;
    };

    getWalletWithNfts("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY");
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    def get_wallet_with_nfts(address: str):
        url = f"https://api.helius.xyz/v1/wallet/{address}/balances"
        params = {
            "api-key": "YOUR_API_KEY",
            "showNfts": "true"
        }

        response = requests.get(url, params=params)
        response.raise_for_status()

        data = response.json()

        print(f"Tokens: {len(data['balances'])}")
        print(f"NFTs: {len(data.get('nfts', []))}")

        # Display NFTs
        for nft in data.get('nfts', []):
            name = nft.get('name', 'Unnamed')
            collection = nft.get('collectionName', 'Unknown Collection')
            print(f"NFT: {name} ({collection})")

        return data

    get_wallet_with_nfts("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY")
    ```
  </Tab>
</Tabs>

### 결과 필터링

쿼리 매개변수를 사용하여 반환되는 내용을 제한합니다:

```javascript theme={"system"}
// Only show tokens with non-zero balances
const url = `https://api.helius.xyz/v1/wallet/${address}/balances?api-key=YOUR_API_KEY&showZeroBalance=false`;

// Exclude native SOL from results
const url = `https://api.helius.xyz/v1/wallet/${address}/balances?api-key=YOUR_API_KEY&showNative=false`;

// Get only the top 50 tokens by value
const url = `https://api.helius.xyz/v1/wallet/${address}/balances?api-key=YOUR_API_KEY&limit=50`;
```

## 쿼리 매개변수

| 매개변수              | 유형      | 기본값   | 설명                      |
| ----------------- | ------- | ----- | ----------------------- |
| `page`            | integer | 1     | 페이지 번호 (1부터 시작)         |
| `limit`           | integer | 100   | 페이지당 최대 토큰 수 (1-100)    |
| `showZeroBalance` | boolean | false | 잔액이 0인 토큰 포함            |
| `showNative`      | boolean | true  | 네이티브 SOL 포함             |
| `showNfts`        | boolean | false | NFT 포함 (최대 100, 첫 페이지만) |

## 응답 형식

```json theme={"system"}
{
  "balances": [
    {
      "mint": "So11111111111111111111111111111111111111111",
      "symbol": "SOL",
      "name": "Solana",
      "balance": 1.5,
      "decimals": 9,
      "pricePerToken": 145.32,
      "usdValue": 217.98,
      "logoUri": "https://raw.githubusercontent.com/solana-labs/token-list/main/assets/mainnet/So11111111111111111111111111111111111111112/logo.png",
      "tokenProgram": "spl-token"
    },
    {
      "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "symbol": "USDC",
      "name": "USD Coin",
      "balance": 1000.5,
      "decimals": 6,
      "pricePerToken": 1.0,
      "usdValue": 1000.5,
      "logoUri": "https://example.com/usdc-logo.png",
      "tokenProgram": "spl-token"
    }
  ],
  "nfts": [
    {
      "mint": "7Xq8wXyXVqfBPPqVJjPDwG9zN5wCVxBYZ6z7vPYBzr6F",
      "name": "Degen Ape #1234",
      "imageUri": "https://example.com/nft.png",
      "collectionName": "Degen Ape Academy",
      "collectionAddress": "DegN1dXmU2uYa4n7U9qTh7YNYpK4u8L9qXx7XqYqJfGH",
      "compressed": false
    }
  ],
  "totalUsdValue": 1218.48,
  "pagination": {
    "page": 1,
    "limit": 100,
    "hasMore": true
  }
}
```

### 필드 노트

* **`balance`**: 사람이 읽을 수 있는 수량, 이미 소수점에 맞게 조정됨 — `1.5`은 1.5 SOL을 의미하고 `1000.5`은 1000.5 USDC를 의미합니다. 람포트 변환이 필요하지 않습니다. 이 엔드포인트는 원래 `amountRaw` 필드를 노출하지 않습니다; 정확한 정수 값을 원하면 `Math.round(balance * 10 ** decimals)`처럼 도출하십시오.
* **`decimals`**: 참조용으로만 제공됩니다.
* **`pricePerToken` / `usdValue`**: DAS 가격 데이터가 없는 토큰을 위한 `null`입니다 (위의 가격 노트를 참조하십시오).
* **`totalUsdValue`**: 현재 응답 페이지에 대한 총 USD 값입니다. 전체 포트폴리오 가치는 모든 페이지를 통해 페이지 매김하고 각 잔액의 `usdValue`을 합산하십시오.
* **`tokenProgram`**: 각 토큰이 사용하는 토큰 표준 — `spl-token` (레거시 SPL 토큰) 또는 `token-2022` (토큰 확장). 두 가지 모두 완전히 지원됩니다.

## 사용 사례

### 포트폴리오 대시보드 구축

USD 값을 사용하여 사용자 보유 내역을 표시합니다:

```javascript theme={"system"}
const renderPortfolio = async (address) => {
  const { balances, totalUsdValue } = await getWalletBalances(address);

  console.log(`Current Page Value: $${totalUsdValue.toLocaleString()}`);
  console.log(`\nTop Holdings:`);

  // totalUsdValue is page-scoped; paginate before computing full portfolio value.
  balances.slice(0, 10).forEach((token, i) => {
    if (token.usdValue) {
      console.log(`${i + 1}. ${token.symbol}: ${token.balance.toFixed(4)} ($${token.usdValue.toFixed(2)})`);
    }
  });
};
```

### 토큰 집중도 계산

포트폴리오 다각화를 분석합니다:

```javascript theme={"system"}
const analyzeConcentration = async (address) => {
  const { balances, totalUsdValue } = await getWalletBalances(address);

  const tokensWithValue = balances.filter(t => t.usdValue);

  if (tokensWithValue.length === 0) {
    console.log('No tokens with USD pricing data available');
    return null;
  }

  const topToken = tokensWithValue[0];
  const pageConcentration = (topToken.usdValue / totalUsdValue) * 100;

  console.log(`Largest Position on Current Page: ${topToken.symbol} (${pageConcentration.toFixed(1)}%)`);

  if (pageConcentration > 50) {
    console.log(`Warning: Current page is highly concentrated in ${topToken.symbol}`);
  }

  return { topToken, pageConcentration };
};
```

### 특정 토큰 잔액 추적

여러 지갑에서 특정 토큰을 모니터링합니다:

```javascript theme={"system"}
const getTokenBalance = async (address, tokenMint) => {
  const { balances } = await getWalletBalances(address);

  const token = balances.find(t => t.mint === tokenMint);

  if (!token) {
    console.log(`Token not found in wallet`);
    return null;
  }

  console.log(`${token.symbol} Balance: ${token.balance}`);
  console.log(`USD Value: $${token.usdValue || 'N/A'}`);

  return token;
};

// Example: Check USDC balance
getTokenBalance(
  "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY",
  "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" // USDC mint
);
```

### 세금 보고를 위한 보유 내역 내보내기

보유 내역 스냅샷을 생성합니다:

```javascript theme={"system"}
const exportHoldingsSnapshot = async (address) => {
  const { balances, totalUsdValue } = await getWalletBalances(address);

  const snapshot = {
    date: new Date().toISOString(),
    address,
    pageValueUSD: totalUsdValue,
    holdings: balances
      .filter(t => t.usdValue)
      .map(t => ({
        symbol: t.symbol,
        mint: t.mint,
        balance: t.balance,
        pricePerToken: t.pricePerToken,
        usdValue: t.usdValue
      }))
  };

  console.log(JSON.stringify(snapshot, null, 2));
  return snapshot;
};
```

## 페이지 매김

100개 이상의 토큰이 있는 지갑의 경우 `page` 매개변수와 `pagination.hasMore`를 사용하여 결과를 페이지 매깁니다:

```javascript theme={"system"}
const getAllBalances = async (address) => {
  let allBalances = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const url = `https://api.helius.xyz/v1/wallet/${address}/balances?api-key=YOUR_API_KEY&page=${page}&limit=100`;

    const response = await fetch(url);
    const data = await response.json();

    allBalances = allBalances.concat(data.balances);
    hasMore = data.pagination.hasMore;
    page++;

    console.log(`Fetched page ${data.pagination.page}, total tokens so far: ${allBalances.length}`);
  }

  console.log(`Total tokens: ${allBalances.length}`);
  return allBalances;
};
```

NFT는 토큰 페이지 매김과 상관없이 첫 번째 페이지에만 반환됩니다 (최대 100).

## 베스트 프랙티스

* **0 잔액을 필터링하여 깔끔한 UI를 만듭니다.** 지갑이 더 이상 보유하지 않는 토큰을 숨기려면 `showZeroBalance=false`를 사용하십시오.
* **필요할 때만 NFT를 포함합니다.** 성능을 위해 기본적으로 NFT는 제외되며, 표시할 때만 `showNfts=true`를 설정하십시오.
* **가격 데이터 누락 처리.** `pricePerToken` 및 `usdValue`가 `null`인지 항상 확인하십시오. 이는 DAS의 시간별 추정치이며 실시간 시장 가격이 아닙니다.
* **응답 캐시.** 잔액 데이터는 몇 초간 캐시하여 API 호출을 줄일 수 있습니다.
* **대규모 지갑 페이지 매김.** 일부 지갑에는 수천 개의 토큰이 있습니다; 페이지 매김을 구현하여 효율적으로 처리하십시오.

## 일반 오류

| 오류 코드 | 설명              | 해결책                           |
| ----- | --------------- | ----------------------------- |
| 400   | 잘못된 지갑 주소 형식    | 주소가 유효한 base58 Solana 주소인지 확인 |
| 401   | 누락되거나 잘못된 API 키 | 요청에 API 키가 포함되어 있는지 확인        |
| 429   | 속도 제한 초과        | 요청 빈도를 줄이거나 플랜 업그레이드          |

## 다음 단계

<CardGroup cols={3}>
  <Card title="과거 잔액" icon="clock" href="/docs/ko/wallet-api/balance-at">
    과거 타임스탬프, 날짜 및 슬롯에서 토큰 또는 SOL 잔액을 가져옵니다.
  </Card>

  <Card title="지갑 API 개요" icon="wallet" href="/docs/ko/wallet-api/overview">
    모든 지갑 API 엔드포인트 및 공유 규칙.
  </Card>

  <Card title="API 참조" icon="code" href="/docs/ko/api-reference/wallet-api/balances">
    지갑 잔액을 위한 요청 및 응답 스키마.
  </Card>
</CardGroup>