> ## 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. # getHistoricalTokenAccountsByOwner > 과거 슬롯 또는 특정 트랜잭션 직후에 Solana 지갑이 소유했던 SPL Token 및 Token-2022 계정을 민트 필터와 페이지네이션을 사용해 나열합니다. > [!NOTE] > > `getHistoricalTokenAccountsByOwner`은 베타 버전입니다. 매개변수, 가격, 응답 형식 및 데이터 범위가 변경될 수 있습니다. ## 개요 `getHistoricalTokenAccountsByOwner`은 과거 슬롯 또는 해당 슬롯의 특정 트랜잭션 직후에 지갑이 소유했던 SPL Token 및 Token-2022 계정을 반환합니다. Helius 전용 RPC 메서드입니다. 표준 `getTokenAccountsByOwner`은 현재 상태만 반환합니다. `jsonParsed` 인코딩을 사용하면 토큰 수량에 요청한 위치 시점의 각 민트 소수 자릿수가 적용되므로, 잔액에는 해당 시점에 지갑이 보유했던 수량이 반영됩니다. 기록은 슬롯 444,959,999(2026년 9월 7일)부터 사용할 수 있으며, 이는 에포크 1030 시작 시점의 상태입니다. `getHistoricalTokenAccountsByOwner`은 Business 이상 요금제의 메인넷에서 사용할 수 있으며, 베타 기간에는 호출당 0크레딧이 부과됩니다. 가격은 변경될 수 있습니다. ## getTokenAccountsByOwner와의 차이점 * **민트 또는 프로그램 필터는 선택 사항입니다.** 필터를 지정하지 않으면 지갑이 소유했던 모든 토큰 계정을 가져옵니다. 결과 범위를 좁히려면 구성 객체(세 번째 매개변수)에 `mint` 또는 `programId` 중 하나만 설정하세요. * **두 번째 매개변수는 쿼리 객체입니다.** 민트 또는 프로그램 필터가 아니라 기록에서의 위치를 선택합니다. * **`result.value`은 객체입니다.** 배열이 아니라 `accounts` 및 `paginationKey`이 포함된 객체입니다. ## 기록에서 위치 선택 두 번째 매개변수는 쿼리 객체입니다. * **생략하거나 `{}`**: 요청한 커밋먼트를 상한으로 하는 가장 최근에 인덱싱된 슬롯입니다. * **`{ "slot": 445000000 }`**: 슬롯 445,000,000의 끝입니다. * **`{ "slot": 445000000, "transactionIndex": 10 }`**: 해당 슬롯에서 인덱스 10의 트랜잭션이 실행된 직후입니다. 위치의 작동 방식은 [과거 계정 가이드](https://www.helius.dev/docs/ko/rpc/historical-accounts.md)를 참조하세요. ## 요청 예시 이 요청은 슬롯 445,000,000의 끝에서 지갑이 보유한 USDC 토큰 계정을 반환합니다. ```bash theme={"system"} curl https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": "1", "method": "getHistoricalTokenAccountsByOwner", "params": [ "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY", { "slot": 445000000 }, { "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "encoding": "jsonParsed" } ] }' ``` ## 모든 토큰 계정 페이지네이션 결과는 민트순으로 정렬된 후 토큰 계정 주소순으로 정렬됩니다. 각 응답은 `value.accounts`과 `:` 형식의 커서인 `value.paginationKey`을 반환합니다. `null`이 될 때까지 다음 요청에 다시 전달하세요. > [!WARNING] > > 페이지가 짧거나 비어 있어도 `paginationKey`이 포함될 수 있습니다. `paginationKey`이 `null`인 경우에만 마지막에 도달한 것입니다. 페이지네이션할 때는 항상 `slot`을 명시적으로 전달하세요. 이를 생략하면 각 페이지가 가장 최근에 인덱싱된 슬롯을 읽으므로 서로 다른 시점의 페이지가 반환될 수 있습니다. ```typescript theme={"system"} const url = `https://mainnet.helius-rpc.com/?api-key=${process.env.HELIUS_API_KEY}`; async function getTokenAccountsAt(owner: string, slot: number) { const accounts = []; let paginationKey: string | null = null; do { const response = await fetch(url, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ jsonrpc: "2.0", id: "1", method: "getHistoricalTokenAccountsByOwner", params: [ owner, { slot }, { encoding: "jsonParsed", limit: 1000, ...(paginationKey && { paginationKey }) }, ], }), }); const { result, error } = await response.json(); if (error) throw new Error(`${error.code}: ${error.message}`); accounts.push(...result.value.accounts); paginationKey = result.value.paginationKey; } while (paginationKey); return accounts; } const tokenAccounts = await getTokenAccountsAt("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY", 445000000); ``` ## 응답 읽기 `value.accounts`의 각 항목에는 토큰 계정의 `pubkey`와 `account` 객체가 있습니다. 계정 객체에는 `getAccountInfo`과 동일한 필드에 더해 `lastUpdatedAt`이 포함됩니다. * \*\*`lastUpdatedAt.slot`\*\*과 \*\*`lastUpdatedAt.transactionIndex`\*\*은 이 상태를 생성한 쓰기 작업을 식별합니다. * **`lastUpdatedAt.slot`이 444,959,999이고 `transactionIndex`이 `null`인 경우** 기록 범위가 시작된 후 토큰 계정이 변경되지 않았음을 의미합니다. * \*\*`context.slot`\*\*은 쿼리한 슬롯이 아니라 Helius가 요청을 처리할 때 인덱싱한 가장 최근 슬롯입니다. ## 오류 | 코드 | 의미 | | - | - | | `-32018` | 슬롯이 기록 범위 시작점(슬롯 444,959,999)보다 이전입니다. | | `-32004` | 슬롯이 요청한 커밋먼트에서 허용하는 범위보다 최신입니다. `confirmed`을 사용하거나 이전 슬롯을 쿼리하세요. | | `-32602` | `mint`과 `programId`을 모두 지정했거나, `programId`이 토큰 프로그램이 아니거나, `paginationKey`의 민트가 `mint`과 일치하지 않는 등 매개변수가 잘못되었습니다. | | `-32601` | 메서드를 찾을 수 없습니다. Helius 메인넷 또는 Gatekeeper 엔드포인트를 호출하세요. 이 메서드는 devnet에서 사용할 수 없습니다. | ## 관련 메서드 > [card] [Historical Accounts Guide](https://www.helius.dev/docs/ko/rpc/historical-accounts.md) > > 과거 계정 메서드에서 위치, 범위 및 lastUpdatedAt이 작동하는 방식 > [card] [getHistoricalAccountInfo](https://www.helius.dev/docs/ko/api-reference/rpc/http/gethistoricalaccountinfo.md) > > 과거 슬롯의 단일 계정 읽기 > [card] [getTransactionsForAddress](https://www.helius.dev/docs/ko/rpc/gettransactionsforaddress.md) > > 검사하려는 트랜잭션의 슬롯 및 transactionIndex 찾기 > [card] [getTokenAccountsByOwnerV2](https://www.helius.dev/docs/ko/api-reference/rpc/http/gettokenaccountsbyownerv2.md) > > 지갑의 현재 토큰 계정 페이지네이션 ## 요청 매개변수 **owner** `string` *required* 토큰 계정을 소유했던 지갑의 Base-58 인코딩 주소입니다. 토큰 계정이 아니라 소유자 지갑을 전달하세요. **slot** `number` 상태를 읽을 슬롯입니다. 이 슬롯의 끝 시점에 해당하는 계정을 반환합니다. 지원되는 가장 이른 슬롯은 에포크 1030 시작 시점의 상태인 444959999입니다. 생략하면 요청한 커밋먼트를 상한으로 하는 가장 최근에 인덱싱된 슬롯을 읽습니다. **transactionIndex** `number` 슬롯 내 트랜잭션의 위치입니다. 슬롯 끝이 아니라 해당 트랜잭션이 실행된 직후의 계정 상태를 반환합니다. slot이 필요합니다. **mint** `string` 이 민트의 토큰 계정만 반환합니다. programId와 함께 사용할 수 없습니다. **programId** `string` 이 토큰 프로그램이 소유한 토큰 계정만 반환합니다. mint와 함께 사용할 수 없습니다. * `TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA` * `TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb` **encoding** `string` (default: base64) 계정 데이터의 인코딩 형식입니다. jsonParsed를 사용하면 토큰 수량에 요청한 위치 시점의 민트 소수 자릿수가 적용됩니다. base58 및 binary는 지원되지 않습니다. * `base64` * `base64+zstd` * `jsonParsed` **dataSlice** `object` 각 계정 데이터의 일부만 반환합니다. base64 및 base64+zstd 인코딩에 적용됩니다. **dataSlice.offset** `number` *required* 읽기를 시작할 바이트 오프셋입니다. **dataSlice.length** `number` *required* 반환할 바이트 수입니다. **limit** `number` (default: 5000) 반환할 토큰 계정의 최대 개수입니다(1\~5,000개). **paginationKey** `string` 이전 응답의 paginationKey에서 가져온 `<mint>:<tokenAccount>` 형식의 커서입니다. mint도 설정하면 커서의 민트가 해당 값과 일치해야 합니다. **commitment** `string` (default: finalized) 커밋먼트 수준입니다. processed는 지원되지 않습니다. * `finalized` * `confirmed` **minContextSlot** `number` 요청을 평가할 수 있는 최소 슬롯입니다. ## OpenAPI ````yaml ko/openapi/rpc-http/getHistoricalTokenAccountsByOwner.yaml POST / openapi: 3.1.0 info: title: Solana RPC API version: 1.0.0 description: >- 과거 슬롯에서 지갑이 소유했던 SPL Token 및 Token-2022 계정을 나열하는 과거 Solana 토큰 계정 API입니다. 선택적으로 민트 또는 토큰 프로그램 필터와 커서 기반 페이지네이션을 사용할 수 있습니다. license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - url: https://mainnet.helius-rpc.com description: 메인넷 RPC 엔드포인트 security: [] paths: /: post: tags: - RPC summary: getHistoricalTokenAccountsByOwner description: | **베타.** 매개변수, 응답 형식 및 데이터 범위가 변경될 수 있습니다. 과거 슬롯에서 지갑이 소유했던 SPL Token 및 Token-2022 계정이나 해당 슬롯 내 특정 트랜잭션 직후의 계정을 반환합니다. 이 Helius RPC 메서드는 기본적으로 모든 토큰 계정을 반환합니다. 구성 객체에서 민트 또는 토큰 programId를 지정하여 결과 범위를 좁히세요. 결과는 민트순으로 정렬된 후 토큰 계정 주소순으로 정렬됩니다. 페이지가 짧거나 비어 있어도 paginationKey가 반환될 수 있습니다. paginationKey가 null이 될 때까지 페이지를 계속 조회하세요. operationId: getHistoricalTokenAccountsByOwner requestBody: required: true content: application/json: schema: type: object required: - jsonrpc - id - method - params properties: jsonrpc: type: string enum: - '2.0' example: '2.0' description: JSON-RPC 프로토콜 버전입니다. default: '2.0' id: type: string example: '1' description: 요청의 고유 식별자입니다. default: '1' method: type: string enum: - getHistoricalTokenAccountsByOwner example: getHistoricalTokenAccountsByOwner description: 호출할 RPC 메서드의 이름입니다. default: getHistoricalTokenAccountsByOwner params: type: array description: 소유자 지갑 주소, 기록 내 위치를 선택하는 선택적 쿼리 객체, 선택적 구성 객체가 포함된 배열입니다. minItems: 1 maxItems: 3 default: - 86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY - slot: 445000000 - encoding: jsonParsed limit: 2 items: oneOf: - type: string title: 소유자 description: >- 토큰 계정을 소유했던 지갑의 Base-58 인코딩 주소입니다. 토큰 계정이 아니라 소유자 지갑을 전달하세요. example: 86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY - $ref: '#/components/schemas/HistoricalAccountQuery' title: 쿼리 - type: object title: 구성 description: 선택적 구성 객체입니다. mint와 programId 중 최대 하나만 설정하세요. properties: mint: type: string description: 이 민트의 토큰 계정만 반환합니다. programId와 함께 사용할 수 없습니다. example: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v programId: type: string description: 이 토큰 프로그램이 소유한 토큰 계정만 반환합니다. mint와 함께 사용할 수 없습니다. enum: - TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA - TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb example: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA encoding: type: string description: >- 계정 데이터의 인코딩 형식입니다. jsonParsed를 사용하면 토큰 수량은 요청한 위치에서의 민트 소수 자릿수를 사용합니다. base58과 binary는 지원되지 않습니다. enum: - base64 - base64+zstd - jsonParsed default: base64 example: jsonParsed dataSlice: $ref: '#/components/schemas/DataSliceConfig' limit: type: integer description: 반환할 토큰 계정의 최대 개수입니다(1~5,000). minimum: 1 maximum: 5000 default: 5000 example: 1000 paginationKey: type: string description: >- 이전 응답의 paginationKey에 있는 커서로, 형식은 `:`입니다. mint도 설정한 경우 커서의 민트가 해당 값과 일치해야 합니다. example: >- 11112zAgXhc6hGfdfr5anSY91mq7Cs4HHpSVEQc4ASG:EKyGnXReqmmXyqBHmMjV2CKCLafJS47xyhXXZ5WuFMxD commitment: type: string description: 커미트먼트 수준입니다. processed는 지원되지 않습니다. enum: - finalized - confirmed default: finalized example: finalized minContextSlot: type: integer description: 요청을 평가할 수 있는 최소 슬롯입니다. example: 445000000 additionalProperties: false responses: '200': description: 과거 토큰 계정 페이지를 성공적으로 가져왔습니다. content: application/json: schema: type: object properties: jsonrpc: type: string description: JSON-RPC 프로토콜 버전입니다. enum: - '2.0' example: '2.0' id: type: string description: 요청과 일치하는 식별자입니다. example: '1' result: type: object properties: context: $ref: '#/components/schemas/HistoricalContext' value: type: object properties: accounts: type: array description: 이 페이지의 토큰 계정으로, 민트순으로 정렬된 후 토큰 계정 주소순으로 정렬됩니다. items: $ref: '#/components/schemas/HistoricalKeyedAccount' paginationKey: oneOf: - type: string - type: 'null' description: >- 다음 페이지의 커서로, 형식은 `:`입니다. 모든 계정이 반환되면 null입니다. paginationKey가 있는 짧거나 빈 페이지는 끝에 도달했다는 의미가 아니라 검색이 조기에 중지되었다는 의미입니다. example: >- 11112zAgXhc6hGfdfr5anSY91mq7Cs4HHpSVEQc4ASG:EKyGnXReqmmXyqBHmMjV2CKCLafJS47xyhXXZ5WuFMxD '400': description: 잘못된 요청 - 요청 매개변수가 유효하지 않거나 요청 형식이 잘못되었습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: jsonrpc: '2.0' error: code: -32602 message: 유효하지 않은 매개변수 id: '1' '401': description: 인증되지 않음 - API 키가 유효하지 않거나 누락되었습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: jsonrpc: '2.0' error: code: -32001 message: 인증되지 않음 id: '1' '429': description: 요청이 너무 많음 - 요청 한도를 초과했습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: jsonrpc: '2.0' error: code: -32005 message: 요청이 너무 많음 id: '1' '500': description: 내부 서버 오류 - 서버에서 오류가 발생했습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: jsonrpc: '2.0' error: code: -32603 message: 내부 오류 id: '1' '503': description: 서비스를 사용할 수 없음 - 서비스를 일시적으로 사용할 수 없습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: jsonrpc: '2.0' error: code: -32002 message: 서비스를 사용할 수 없음 id: '1' '504': description: 게이트웨이 시간 초과 - 요청 시간이 초과되었습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: jsonrpc: '2.0' error: code: -32003 message: 게이트웨이 시간 초과 id: '1' security: - ApiKeyQuery: [] components: schemas: HistoricalAccountQuery: type: object description: 읽을 기록 내 위치입니다. 최신 인덱싱 슬롯을 읽으려면 생략하거나 빈 객체를 전송하세요. properties: slot: type: integer description: >- 상태를 읽을 슬롯입니다. 이 슬롯이 끝난 시점의 계정을 반환합니다. 지원되는 가장 이른 슬롯은 444959999이며, 이는 에포크 1030이 시작될 때의 상태입니다. 생략하면 요청한 커미트먼트로 제한된 최신 인덱싱 슬롯을 읽습니다. minimum: 444959999 example: 445000000 transactionIndex: type: integer description: >- 슬롯 내 트랜잭션의 위치입니다. 슬롯 종료 시점 대신 해당 트랜잭션이 실행된 직후의 계정 상태를 반환합니다. slot이 필요합니다. minimum: 0 maximum: 16777214 example: 10 additionalProperties: false DataSliceConfig: type: object description: 각 계정 데이터의 일부만 반환합니다. base64 및 base64+zstd 인코딩에 적용됩니다. properties: offset: type: integer description: 읽기를 시작할 바이트 오프셋입니다. example: 0 length: type: integer description: 반환할 바이트 수입니다. example: 8 required: - offset - length HistoricalContext: type: object description: 응답 메타데이터입니다. properties: slot: type: integer description: 요청을 처리할 당시 기록 저장소가 인덱싱한 최신 슬롯입니다. 조회한 슬롯과는 다릅니다. example: 468129571 HistoricalKeyedAccount: type: object properties: pubkey: type: string description: 토큰 계정의 Base-58 인코딩 주소입니다. example: EKyGnXReqmmXyqBHmMjV2CKCLafJS47xyhXXZ5WuFMxD account: $ref: '#/components/schemas/HistoricalAccount' required: - pubkey - account ErrorResponse: type: object properties: jsonrpc: type: string description: JSON-RPC 프로토콜 버전입니다. enum: - '2.0' example: '2.0' error: type: object properties: code: type: integer description: 오류 코드입니다. example: -32602 message: type: string description: 오류 메시지입니다. data: type: object description: 오류에 관한 추가 데이터입니다. id: type: string description: 요청과 일치하는 식별자입니다. example: '1' HistoricalAccount: type: object description: 요청한 위치의 계정 상태와 해당 상태가 마지막으로 기록된 위치입니다. properties: lamports: type: integer description: 이 계정에 할당된 lamport 수입니다. example: 531589475273 owner: type: string description: 이 계정이 할당된 프로그램의 Base-58 인코딩 공개 키입니다. example: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA data: description: >- 계정 데이터입니다. base64 또는 base64+zstd에서는 인코딩된 데이터와 인코딩으로 구성된 2개 항목의 배열입니다. jsonParsed에서는 program, parsed, space가 포함된 객체입니다. 파싱할 수 없는 계정은 base64 배열로 대체됩니다. oneOf: - type: array items: type: string - type: object properties: program: type: string description: 계정을 소유한 프로그램의 이름입니다. example: spl-token parsed: type: object description: 프로그램별로 파싱된 계정 상태입니다. space: type: integer description: 계정의 데이터 크기입니다. example: 82 executable: type: boolean description: 계정에 프로그램이 포함되어 있는지 여부입니다. example: false rentEpoch: type: integer description: 이 계정에 다음 임대료가 부과될 에포크입니다. 임대료 면제 계정은 최대 u64 값을 보고합니다. space: type: integer description: 계정의 데이터 크기(바이트)입니다. example: 82 lastUpdatedAt: $ref: '#/components/schemas/AccountWritePosition' required: - lamports - owner - data - executable - rentEpoch - space - lastUpdatedAt AccountWritePosition: type: object description: 요청한 위치 또는 그 이전에 반환된 상태가 마지막으로 기록된 위치입니다. properties: slot: type: integer description: >- 마지막 쓰기의 슬롯입니다. transactionIndex가 null이고 값이 444959999이면 기록 범위가 시작된 이후 계정이 변경되지 않았음을 의미합니다. example: 444999837 transactionIndex: oneOf: - type: integer - type: 'null' description: >- 마지막 쓰기를 수행한 트랜잭션의 위치입니다. 쓰기가 트랜잭션 외부에서 발생했거나(예: 에포크 보상), 기록 범위가 시작된 이후 계정이 변경되지 않은 경우 null입니다. example: 700 required: - slot - transactionIndex securitySchemes: ApiKeyQuery: type: apiKey in: query name: api-key description: >- Helius API 키입니다. [대시보드](https://dashboard.helius.dev/api-keys)에서 무료로 받을 수 있습니다. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.