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

# getTokenAccountBalance 사용 방법

> getTokenAccountBalance 사용 사례, 코드 예제, 요청 매개변수, 응답 구조 및 팁을 학습합니다.

[`getTokenAccountBalance`](https://www.helius.dev/docs/api-reference/rpc/http/gettokenaccountbalance) RPC 메서드는 특정 SPL 토큰 계정의 토큰 잔액을 반환합니다. 이는 특정 토큰 계정이 보유한 토큰 수량을 표시하거나 확인해야 하는 애플리케이션에 필수적입니다.

## 일반적인 사용 사례

* **사용자 토큰 잔액 표시:** 사용자가 지갑(연관된 토큰 계정)에서 특정 토큰을 얼마나 소유하고 있는지 보여줍니다.
* **토큰 가용성 확인:** 전송이나 기타 작업을 시도하기 전에 토큰 계정에 충분한 잔액이 있는지 확인합니다.
* **포트폴리오 추적:** 사용자의 다양한 토큰 계정에 대한 토큰 잔액을 집계합니다.
* **스마트 계약 상호작용:** 스마트 계약은 논리의 일부로 토큰 잔액을 쿼리할 수 있습니다(블록체인 프로그램은 일반적으로 계정 정보에서 이 데이터를 직접 액세스합니다).

## 요청 매개변수

1. **토큰 계정 공개 키** (string, required): 쿼리하려는 SPL 토큰 계정의 base-58로 인코딩된 공개 키입니다.
2. **구성 객체** (object, optional): 다음 필드를 포함할 수 있는 선택적 객체입니다:
   * **`commitment`** (string, optional): 쿼리에 대한 [커밋 수준](https://www.helius.dev/blog/solana-commitment-levels)을 지정합니다. 생략 시 RPC 노드의 기본 커밋이 사용됩니다(보통 `finalized`).

## 응답 구조

JSON-RPC 응답의 `result` 필드는 `context`와 `value` 필드를 가진 객체를 포함합니다. `value` 객체는 잔액 정보를 보유합니다:

* **`amount`** (string): 토큰 계정의 원시 잔액을 문자열로 나타냅니다. 이는 토큰의 가장 작은 단위를 나타내는 정수입니다(예: 토큰이 소수 6자리인 경우, "1000000"은 1 토큰을 의미합니다).
* **`decimals`** (u8): 이 토큰 유형에 정의된 소수 자릿수(토큰 발행에 의해).
* **`uiAmount`** (number | null): `decimals`를 반영하여 부동 소수점 숫자로 형식화된 잔액입니다. 이 필드는 일부 컨텍스트에서 `null` 또는 `uiAmountString` 대신 사용되지 않을 수 있습니다.
* **`uiAmountString`** (string): `decimals`를 고려하여 문자열로 형식화된 잔액입니다. 부동 소수점 부정확성을 피하기 위해 표시를 위해 자주 사용됩니다.

**응답 예제:**

```json theme={"system"}
{
  "jsonrpc": "2.0",
  "result": {
    "context": {
      "slot": 183457201
    },
    "value": {
      "amount": "500000000",
      "decimals": 9,
      "uiAmount": 0.5,
      "uiAmountString": "0.5"
    }
  },
  "id": 1
}
```

## 코드 예제

<CodeGroup>
  ```bash cURL theme={"system"}
  # Basic Request (replace <TOKEN_ACCOUNT_PUBKEY>):
  curl -X POST -H "Content-Type: application/json" -d \
    '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "getTokenAccountBalance",
      "params": [
        "<TOKEN_ACCOUNT_PUBKEY>"
      ]
    }' \
    <YOUR_RPC_URL>

  # Request with commitment (replace <TOKEN_ACCOUNT_PUBKEY>):
  curl -X POST -H "Content-Type: application/json" -d \
    '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "getTokenAccountBalance",
      "params": [
        "<TOKEN_ACCOUNT_PUBKEY>",
        {
          "commitment": "confirmed"
        }
      ]
    }' \
    <YOUR_RPC_URL>
  ```

  ```javascript JavaScript (using @solana/web3.js) theme={"system"}
  const { Connection, PublicKey } = require('@solana/web3.js');

  async function checkTokenBalance(tokenAccountPublicKey) {
    // Replace with your RPC endpoint
    const connection = new Connection('https://mainnet.helius-rpc.com/?api-key=<api-key>');
    
    try {
      const tokenAccountPubKey = new PublicKey(tokenAccountPublicKey);
      const balance = await connection.getTokenAccountBalance(tokenAccountPubKey);

      if (!balance.value) {
          console.log(`Could not find token account: ${tokenAccountPublicKey}`);
          return;
      }

      console.log(`Token Account: ${tokenAccountPublicKey}`);
      console.log(`Raw Amount: ${balance.value.amount}`);
      console.log(`Decimals: ${balance.value.decimals}`);
      console.log(`UI Amount (string): ${balance.value.uiAmountString}`);
      // console.log(JSON.stringify(balance, null, 2)); // For full response details

    } catch (error) {
      console.error(`Error fetching token account balance for ${tokenAccountPublicKey}:`, error);
    }
  }

  // Replace with an actual SPL Token Account Public Key
  const exampleTokenAccount = 'HHisAGTT6ADDd52jY1g65Akn3N2f4jSdQS2rTiyDEw5c'; // Example: An account holding some USDC on mainnet
  checkTokenBalance(exampleTokenAccount);

  // Example for a token account that might not exist or have 0 balance
  // const nonExistentAccount = '11111111111111111111111111111111'; 
  // checkTokenBalance(nonExistentAccount);
  ```
</CodeGroup>

## 개발자 팁

* **토큰 계정 vs. 민트 계정 vs. 소유자 계정:** 토큰의 *민트 주소* 또는 *소유자의 지갑 주소*가 아닌 *SPL 토큰 계정*의 공개 키를 제공하세요. 보통 `getTokenAccountsByOwner`를 사용하여 소유자에 대한 토큰 계정을 얻습니다.
* **소수점:** `amount`를 올바르게 해석하려면 항상 `decimals` 필드를 사용하세요. 부동 소수점 정밀도 문제를 피하기 위해 `uiAmountString`이 `uiAmount`보다 표시를 위해 일반적으로 안전합니다.
* **존재하지 않는 계정:** 제공된 공개 키가 기존 토큰 계정에 해당하지 않으면, RPC 제공자나 라이브러리에 따라 동작이 약간 다를 수 있지만, 종종 응답의 `value`가 `null`이거나 오류가 발생합니다. JavaScript 예제에는 `balance.value`에 대한 기본적인 확인이 포함되어 있습니다.
* **커밋 수준:** 다른 커밋 수준을 사용하면 특히 최근의 거래에 대해 잔액 변화를 얼마나 빨리 볼 수 있는지에 영향을 미칠 수 있습니다. `finalized`는 가장 안전하지만 지연 시간이 가장 깁니다.

이 가이드는 `getTokenAccountBalance` 메서드를 사용하여 SPL 토큰 잔액을 정확하게 검색하고 해석하는 데 도움이 될 것입니다.

## 관련 메서드

<CardGroup cols={2}>
  <Card title="getTokenAccountsByOwner" href="/docs/ko/api-reference/rpc/http/gettokenaccountsbyowner">
    소유자에 대한 모든 토큰 계정 가져오기
  </Card>

  <Card title="getTokenSupply" href="/docs/ko/api-reference/rpc/http/gettokensupply">
    토큰 발행의 총 공급량 가져오기
  </Card>
</CardGroup>