Skip to main content
getTokenAccountsByOwner RPC 메서드는 특정 공개 키가 소유한 모든 SPL 토큰 계정을 검색하는 데 사용됩니다. 이는 사용자의 토큰 보유를 표시하거나 다양한 토큰 계정과 상호 작용해야 하는 지갑 및 애플리케이션에 중요한 메서드입니다. 쿼리를 특정 토큰 mint 또는 programId (예: SPL 토큰 프로그램 또는 Token-2022 프로그램)으로 필터링해야 합니다. 광범위한 토큰 포트폴리오를 보유한 지갑의 경우 최대 10,000개의 계정을 요청당 구성 가능한 페이지 크기로 지원하는 커서 기반 페이지 매김을 제공하는 getTokenAccountsByOwnerV2를 사용하는 것을 고려하십시오.

일반적인 사용 사례

  • 사용자 포트폴리오 표시: 주어진 사용자의 지갑 주소에 대한 모든 토큰 계정(따라서 잔액)을 가져와 전체 토큰 포트폴리오를 표시합니다.
  • 애플리케이션 로직: 전송이나 기타 상호작용을 시작하기 전에 특정 마인트에 대한 사용자의 특정 토큰 계정을 식별합니다.
  • 검증: 소유자가 특정 유형의 토큰에 대해 어떤 토큰 계정을 보유하고 있는지 확인합니다.
  • 토큰 소유자 색인화: 다른 방법보다 전역 색인화에 비효율적이지만, 알려진 소유자 집합을 위한 계정을 찾는 데 사용할 수 있습니다.

요청 매개변수

  1. ownerPubkey (문자열, 필수): 검색하려는 계정 소유자의 base-58로 인코딩된 공개 키입니다.
  2. filter (객체, 필수): mint 또는 programId 중 하나를 지정해야 하는 JSON 객체:
    • mint (문자열): 특정 토큰 마인트의 base-58로 인코딩된 공개 키입니다. 제공되면 ownerPubkey가 소유한 이 마인트에 대한 토큰 계정만 반환됩니다.
    • programId (문자열): 계정을 관리하는 토큰 프로그램의 base-58로 인코딩된 공개 키입니다. 일반적인 값은 다음과 같습니다:
      • SPL 토큰 프로그램: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
      • Token-2022 프로그램: TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb
  3. options (객체, 선택적): 포함할 수 있는 선택적 구성 객체:
    • commitment (문자열, 선택적): 커밋먼트 레벨을 지정합니다.
    • encoding (문자열, 선택적): 계정 데이터의 인코딩. "jsonParsed"가 강력히 권장됩니다. 다른 옵션: "base64", "base64+zstd". 기본값은 "base64"입니다.
    • dataSlice (객체, 선택적): 계정 데이터의 특정 슬라이스를 검색합니다 (offset: usize, length: usize). base58, base64, base64+zstd 인코딩에만 해당됩니다.
    • minContextSlot (u64, 선택적): 쿼리의 최소 슬롯입니다.

응답 구조

JSON-RPC 응답의 result.value 필드는 객체 배열입니다. 각 객체는 ownerPubkey가 소유하고 filter와 일치하는 SPL 토큰 계정에 해당합니다. value 배열의 각 객체는 다음을 포함합니다:
  • pubkey (문자열): 토큰 계정 자체의 base-58로 인코딩된 공개 키.
  • account (객체): 토큰 계정에 대한 자세한 정보:
    • lamports (u64): 임대 면제를 위한 Lamport 잔액.
    • owner (문자열): 소유 프로그램(예: 토큰 프로그램 공개 키).
    • data: 계정 데이터. "jsonParsed" 인코딩이 사용되면 다음을 포함합니다:
      • program (문자열): 예: "spl-token".
      • parsed: 구조화된 정보를 가진 객체:
        • info: 다음과 같은 세부 사항 포함:
          • mint (문자열): 토큰의 마인트 주소.
          • owner (문자열): 토큰 계정의 소유자(요청의 ownerPubkey와 일치해야 합니다).
          • tokenAmount (객체): 토큰의 잔액 (amount, decimals, uiAmount, uiAmountString).
          • state (문자열): 토큰 계정의 상태 (예: "initialized").
          • isNative (boolean): 계정이 래핑된 SOL을 보유하고 있는지 여부.
          • delegate (문자열, 선택적): 설정된 위임자 주소.
          • delegatedAmount (객체, 선택적): 위임자가 설정된 경우 위임된 금액.
        • type (문자열): 예: "account".
    • executable (boolean): 계정이 실행 가능한지 여부.
    • rentEpoch (u64): 다음 에포크 임대가 만료되는 시점.
    • space (u64, jsonParsed가 아닌 경우): 바이트 단위의 원시 계정 데이터 길이.
예제 응답 (jsonParsed 인코딩, programId로 필터링됨):

코드 예제

개발자 팁

  • 필터 필요: 필터에서 mint 또는 programId 중 하나를 제공해야 합니다. 이러한 기본 필터 중 하나 없이 소유자의 모든 토큰 유형에 대한 모든 토큰 계정을 쿼리할 수 없습니다.
  • 연관된 토큰 계정: 이 메서드는 기본 연관된 토큰 계정(ATAs)과 그들이 소유할 수 있는 기타 SPL 토큰 계정(예: 이전 지갑 구현이나 커스텀 설정에서 온 계정)을 포함하여 공개 키가 소유한 모든 토큰 계정을 반환합니다.
  • 인코딩: encoding 옵션의 "jsonParsed" 사용을 강력히 권장합니다. 이는 이진 계정 데이터를 보다 사용하기 쉬운 JSON 구조로 해독합니다.
  • 성능: 소유자가 매우 많은 수의 토큰 계정을 보유한 경우(특히 programId로만 필터링할 때), 응답 크기가 클 수 있습니다. 이러한 경우에 대해 getTokenAccountsByOwnerV2를 사용하여 내장된 페이지 매김 지원을 제공합니다.
  • Token-2022 (토큰 확장): 전송 수수료, 이자 등과 같은 확장을 지원하는 Token-2022 프로그램을 사용하여 생성된 토큰으로 작업할 경우 올바른 programId: TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb을 사용하십시오.
이 가이드는 getTokenAccountsByOwner RPC 메서드에 대한 철저한 이해를 제공하여 Solana 주소에 대한 토큰 계정 정보를 효율적으로 검색할 수 있습니다.

대형 토큰 포트폴리오를 위한 페이지 매김

광범위한 토큰 보유를 가진 지갑의 경우 getTokenAccountsByOwnerV2를 사용하십시오. 다음을 제공합니다:
  • 커서 기반 페이지 매김: limit (1-10,000)을 설정하고 paginationKey를 사용하여 결과를 탐색합니다.
  • 증분 업데이트: 특정 슬롯 이후 수정된 토큰 계정만 가져오기 위해 changedSinceSlot 사용
  • 향상된 성능: 시간 초과 예방 및 실시간 포트폴리오 추적 가능
  • 페이지 매김 동작: 페이지 매김의 끝은 토큰 계정이 반환되지 않을 때만 표시됩니다. 필터링으로 인해 제한보다 적은 계정이 반환될 수 있습니다 - paginationKey가 null이 될 때까지 페이지 매김을 계속합니다.

관련 메서드

getTokenAccountsByOwnerV2

대규모 포트폴리오를 위한 커서 기반 내비게이션을 갖춘 페이지 매김 버전

getTokenAccountBalance

특정 토큰 계정의 잔액 가져오기