getTokenAccountBalance RPC 메서드는 특정 SPL 토큰 계정의 토큰 잔액을 반환합니다. 이는 특정 토큰 계정이 보유한 토큰 수량을 표시하거나 확인해야 하는 애플리케이션에 필수적입니다.
일반적인 사용 사례
- 사용자 토큰 잔액 표시: 사용자가 지갑(연관된 토큰 계정)에서 특정 토큰을 얼마나 소유하고 있는지 보여줍니다.
- 토큰 가용성 확인: 전송이나 기타 작업을 시도하기 전에 토큰 계정에 충분한 잔액이 있는지 확인합니다.
- 포트폴리오 추적: 사용자의 다양한 토큰 계정에 대한 토큰 잔액을 집계합니다.
- 스마트 계약 상호작용: 스마트 계약은 논리의 일부로 토큰 잔액을 쿼리할 수 있습니다(블록체인 프로그램은 일반적으로 계정 정보에서 이 데이터를 직접 액세스합니다).
요청 매개변수
- 토큰 계정 공개 키 (string, required): 쿼리하려는 SPL 토큰 계정의 base-58로 인코딩된 공개 키입니다.
- 구성 객체 (object, optional): 다음 필드를 포함할 수 있는 선택적 객체입니다:
commitment(string, optional): 쿼리에 대한 커밋 수준을 지정합니다. 생략 시 RPC 노드의 기본 커밋이 사용됩니다(보통finalized).
응답 구조
JSON-RPC 응답의result 필드는 context와 value 필드를 가진 객체를 포함합니다. value 객체는 잔액 정보를 보유합니다:
amount(string): 토큰 계정의 원시 잔액을 문자열로 나타냅니다. 이는 토큰의 가장 작은 단위를 나타내는 정수입니다(예: 토큰이 소수 6자리인 경우, “1000000”은 1 토큰을 의미합니다).decimals(u8): 이 토큰 유형에 정의된 소수 자릿수(토큰 발행에 의해).uiAmount(number | null):decimals를 반영하여 부동 소수점 숫자로 형식화된 잔액입니다. 이 필드는 일부 컨텍스트에서null또는uiAmountString대신 사용되지 않을 수 있습니다.uiAmountString(string):decimals를 고려하여 문자열로 형식화된 잔액입니다. 부동 소수점 부정확성을 피하기 위해 표시를 위해 자주 사용됩니다.
코드 예제
개발자 팁
- 토큰 계정 vs. 민트 계정 vs. 소유자 계정: 토큰의 민트 주소 또는 소유자의 지갑 주소가 아닌 SPL 토큰 계정의 공개 키를 제공하세요. 보통
getTokenAccountsByOwner를 사용하여 소유자에 대한 토큰 계정을 얻습니다. - 소수점:
amount를 올바르게 해석하려면 항상decimals필드를 사용하세요. 부동 소수점 정밀도 문제를 피하기 위해uiAmountString이uiAmount보다 표시를 위해 일반적으로 안전합니다. - 존재하지 않는 계정: 제공된 공개 키가 기존 토큰 계정에 해당하지 않으면, RPC 제공자나 라이브러리에 따라 동작이 약간 다를 수 있지만, 종종 응답의
value가null이거나 오류가 발생합니다. JavaScript 예제에는balance.value에 대한 기본적인 확인이 포함되어 있습니다. - 커밋 수준: 다른 커밋 수준을 사용하면 특히 최근의 거래에 대해 잔액 변화를 얼마나 빨리 볼 수 있는지에 영향을 미칠 수 있습니다.
finalized는 가장 안전하지만 지연 시간이 가장 깁니다.
getTokenAccountBalance 메서드를 사용하여 SPL 토큰 잔액을 정확하게 검색하고 해석하는 데 도움이 될 것입니다.
관련 메서드
getTokenAccountsByOwner
소유자에 대한 모든 토큰 계정 가져오기
getTokenSupply
토큰 발행의 총 공급량 가져오기