> ## 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.
# getTokenAccountsByOwnerV2
> 특정 지갑 주소에 소유된 SPL 토큰 계정을 효율적으로 검색하기 위한 커서 기반 페이지 매김 및 changedSinceSlot 지원 기능을 포함한 getTokenAccountsByOwner의 향상된 버전입니다.
## 개요
`getTokenAccountsByOwnerV2`는 광범위한 토큰 보유량을 가진 지갑 처리 및 토큰 포트폴리오를 효율적으로 쿼리하기 위해 설계된 표준 `getTokenAccountsByOwner` 메서드의 향상된 버전입니다. 이 메서드는 커서 기반의 페이지 매김 및 증분 업데이트 기능을 도입합니다.
**V2의 새로운 기능:**
* **커서 기반 페이지 매김**: 요청당 1에서 10,000개의 토큰 계정 제한을 구성합니다.
* **증분 업데이트**: `changedSinceSlot`를 사용하여 최근에 수정된 토큰 계정만 가져옵니다.
* **포트폴리오 확장성**: 수천 개의 토큰 계정을 가진 지갑을 효율적으로 처리합니다.
* **하위 호환성**: 모든 기존 `getTokenAccountsByOwner` 매개변수 및 필터를 지원합니다.
* **선택적 `withContext`**: `true`는 `slot` 및 `apiVersion`를 `result.context` 아래에 추가합니다; 제외하거나 `false` 하고 포함되지 않습니다.
**필터 요구사항**: 쿼리에서 `mint` (특정 토큰) 또는 `programId` (SPL 토큰 또는 Token-2022 프로그램)을 제공해야 합니다. 소유자의 모든 토큰 유형을 필터 없이 쿼리하는 것은 지원되지 않습니다.
## 주요 이점
수천 개의 토큰 계정을 가진 지갑을 시간 초과나 메모리 문제 없이 처리합니다.
증분 업데이트를 위한 `changedSinceSlot`를 사용하여 포트폴리오 변경 사항을 실시간으로 모니터링합니다.
## `withContext` (선택 사항)
config 객체(`params[2]`)의 불리언입니다. `result`의 모양만 변경되며, 필터, 제한 또는 페이지 매김은 변경되지 않습니다. 제외하거나 `false`: `result.value`은 토큰 계정 **배열**입니다. `true`: `result.context`와 `result.value`를 **객체**로 포함합니다 (`accounts`, `paginationKey`). 둘 다 처리하는 경우 `Array.isArray(result.value)`에서 나눕니다.
```json theme={"system"}
// Omitted or false
{ "jsonrpc": "2.0", "id": "1", "result": { "value": [], "paginationKey": null } }
// true
{ "jsonrpc": "2.0", "id": "1", "result": {
"context": { "slot": 411895550, "apiVersion": "3.1.9" },
"value": { "accounts": [], "paginationKey": null }
}}
```
## 페이지 매김 모범 사례
**중요한 페이지 매김 동작**: **반환되는 토큰 계정이 없을 때**만 페이지 매김의 끝이 표시됩니다. API는 필터링으로 인해 제한보다 적은 계정을 반환할 수 있습니다 - `paginationKey`가 `null`일 때까지 항상 페이지 매김을 계속하십시오.
### 기본 포트폴리오 쿼리
```typescript theme={"system"}
// Get all SPL Token accounts for a wallet
let allTokenAccounts = [];
let paginationKey = null;
do {
const response = await fetch(`https://mainnet.helius-rpc.com/?api-key=${API_KEY}`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
jsonrpc: '2.0',
id: '1',
method: 'getTokenAccountsByOwnerV2',
params: [
"9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM", // wallet address
{ "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" },
{
encoding: 'jsonParsed',
limit: 1000,
...(paginationKey && { paginationKey })
}
]
})
});
const data = await response.json();
allTokenAccounts.push(...data.result.value);
paginationKey = data.result.paginationKey;
} while (paginationKey);
console.log(`Total token accounts: ${allTokenAccounts.length}`);
```
### 증분 포트폴리오 업데이트
```typescript theme={"system"}
// Get only token accounts modified since a specific slot
const portfolioUpdates = await fetch(`https://mainnet.helius-rpc.com/?api-key=${API_KEY}`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
jsonrpc: '2.0',
id: '1',
method: 'getTokenAccountsByOwnerV2',
params: [
walletAddress,
{ "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" },
{
encoding: 'jsonParsed',
limit: 1000,
changedSinceSlot: lastUpdateSlot // Only get recent changes
}
]
})
});
```
## 토큰 프로그램 지원
**Token-2022 지원**: 확장 기능(전송 수수료, 이자 지급 토큰 등)을 사용하여 Token-2022 계정을 쿼리하려면 `TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb`를 `programId`로 사용하십시오.
```typescript theme={"system"}
// Query Token-2022 accounts (supports token extensions)
const token2022Response = await fetch(`https://mainnet.helius-rpc.com/?api-key=${API_KEY}`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
jsonrpc: '2.0',
id: '1',
method: 'getTokenAccountsByOwnerV2',
params: [
walletAddress,
{ "programId": "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb" }, // Token-2022
{ encoding: 'jsonParsed', limit: 1000 }
]
})
});
```
## getTokenAccountsByOwner에서의 마이그레이션
기존 쿼리에 페이지 매김 매개변수를 추가하면 마이그레이션은 간단합니다:
```diff theme={"system"}
{
"jsonrpc": "2.0",
"id": "1",
- "method": "getTokenAccountsByOwner",
+ "method": "getTokenAccountsByOwnerV2",
"params": [
"9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
{ "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" },
{
"encoding": "jsonParsed",
+ "limit": 1000
}
]
}
```
## 관련 메서드
페이지 매김 없는 원본 메서드
프로그램 계정 쿼리를 위한 V2 메서드
## 요청 매개변수
토큰 보유를 쿼리할 계정 소유자의 Solana 지갑 주소(pubkey)로, base-58 인코딩된 문자열입니다.
특정 토큰 또는 NFT에 대한 계정만 검색하기 위한 특정 Solana 토큰 발행 주소입니다.
토큰 계정을 생성한 특정 Solana 토큰 프로그램 ID (일반적으로 SPL 토큰 프로그램)입니다.
요청에 대한 커밋 수준입니다.
* `confirmed`
* `finalized`
* `processed`
요청을 평가할 수 있는 최소 슬롯입니다.
`true`일 때, `result.context` (스냅샷 메타데이터: `slot`, `apiVersion`)와 함께
`accounts` 및 `paginationKey`를 객체로서 `result.value` 아래에 포함시킵니다. `false`
또는 제외된 경우, `result.value`는 이 페이지의 토큰 계정 배열로,
`result`에서 `paginationKey`와 함께 제공됩니다. 동일한 필터 및 제한이 적용됩니다.
계정의 데이터 슬라이스를 요청합니다.
반환할 바이트 수입니다.
읽기를 시작할 바이트 오프셋입니다.
계정 데이터의 인코딩 형식입니다.
* `base58`
* `base64`
* `base64+zstd`
* `jsonParsed`
요청당 반환할 최대 토큰 계정 수입니다 (1-10,000).
다음 페이지를 가져오기 위한 Base-58 인코딩된 페이지 매김 커서입니다. 이전 응답에서 paginationKey를 사용하십시오.
해당 슬롯 번호에서 또는 그 이후에 수정된 토큰 계정만 반환합니다. 증분 포트폴리오 업데이트에 유용합니다.
## OpenAPI
````yaml ko/openapi/rpc-http/getTokenAccountsByOwnerV2.yaml POST /
openapi: 3.1.0
info:
title: Solana RPC API
version: 1.0.0
description: >-
지갑 주소와 관련된 SPL 토큰 잔액, NFT 및 기타 토큰 보유를 효율적으로 검색하기 위한 커서 기반 페이지네이션 및
changedSinceSlot 지원을 포함한 추가 기능을 갖춘 향상된 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 엔드포인트
- url: https://devnet.helius-rpc.com
description: Devnet RPC 엔드포인트
security: []
paths:
/:
post:
tags:
- RPC
summary: getTokenAccountsByOwnerV2
description: >
특정 지갑 주소가 소유한 대량의 SPL 토큰 계정을 효율적으로 가져오기 위한 커서 기반 페이지네이션 및
changedSinceSlot 지원을 포함한 getTokenAccountsByOwner의 향상된 버전입니다. 요청당 최대
10,000개의 계정의 구성 가능한 페이지 크기로 확장 가능한 포트폴리오 쿼리를 사용할 수 있습니다.
changedSinceSlot 매개변수를 사용하면 특정 블록체인 슬롯 이후에 수정된 토큰 계정만 검색할 수 있어 실시간 포트폴리오
추적 및 지갑 잔액 동기화에 적합합니다. 지갑, 포트폴리오 트래커, DeFi 애플리케이션 및 포괄적인 토큰 보유 데이터가 필요한
서비스에 필수적입니다.
참고: 페이지네이션의 끝은 토큰 계정이 반환되지 않을 때만 표시됩니다. API는 필터링으로 인해 제한보다 적은 계정을 반환할 수
있습니다 - paginationKey가 null이 될 때까지 페이지네이션을 계속하십시오.
**withContext**: 구성 객체에서 선택적 불리언(인코딩, 제한 등과 함께)입니다. `withContext`가
`true`이면 RPC는 표준 Solana 래핑 형태인 `result.context` (스냅샷 메타데이터, `slot` 및
일반적으로 `apiVersion` 포함)와 `result.value`를 객체로 반환하여 `accounts`, 및
`paginationKey`를 포함합니다. `withContext`가 `false`이거나 생략되면, 계정 목록은
`result.value`가 배열(solan classic `getTokenAccountsByOwner`와 동일)이며,
`paginationKey`는 `result`에 있습니다. 필터, 제한 및 페이지네이션 동작은 변경되지 않고 `result`의
JSON 형태만 다릅니다.
operationId: getTokenAccountsByOwnerV2
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
jsonrpc:
type: string
enum:
- '2.0'
description: JSON-RPC 프로토콜 버전입니다.
example: '2.0'
default: '2.0'
id:
type: string
description: 요청에 대한 고유 식별자입니다.
example: '1'
default: '1'
method:
type: string
enum:
- getTokenAccountsByOwnerV2
description: 호출할 RPC 메서드의 이름입니다.
example: getTokenAccountsByOwnerV2
default: getTokenAccountsByOwnerV2
params:
type: array
description: 특정 퍼블릭 키가 소유한 페이지네이션된 토큰 계정을 쿼리하기 위한 매개변수입니다.
default:
- A1TMhSGzQxMr1TboBKtgixKz1sS6REASMxPo1qsyTSJd
- programId: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
- encoding: jsonParsed
limit: 1000
items:
oneOf:
- type: string
description: >-
토큰 보유를 쿼리할 계정 소유자의 Solana 지갑 주소(퍼블릭 키)로, base-58로 인코딩된
문자열입니다.
example: A1TMhSGzQxMr1TboBKtgixKz1sS6REASMxPo1qsyTSJd
- type: object
description: 민트 주소 또는 프로그램 ID를 통해 토큰 계정을 좁히기 위한 필터 구성입니다.
properties:
mint:
type: string
description: 특정 토큰이나 NFT에 대한 계정만 검색하기 위한 특정 Solana 토큰 민트 주소입니다.
example: 2cHr7QS3xfuSV8wdxo3ztuF4xbiarF6Nrgx3qpx3HzXR
programId:
type: string
description: >-
토큰 계정을 생성한 특정 Solana 토큰 프로그램 ID(일반적으로 SPL 토큰
프로그램)입니다.
example: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
- type: object
description: 페이지네이션 지원 및 선택적 필드를 포함한 향상된 구성 객체입니다.
properties:
commitment:
type: string
description: 요청에 대한 커밋 수준입니다.
enum:
- confirmed
- finalized
- processed
example: finalized
minContextSlot:
type: integer
description: 요청이 평가할 수 있는 최소 슬롯입니다.
example: 1000
withContext:
type: boolean
description: >
`true`일 경우 `result.context`(스냅샷 메타데이터: `slot`,
`apiVersion`)를 반환하고 `result.value` 하에 `accounts`와
`paginationKey`를 객체로서 포함합니다. `false`이거나 생략된 경우
`result.value`는 이 페이지의 토큰 계정 배열이며,
`paginationKey`는 `result`에 있습니다. 동일한 필터와 제한이
적용됩니다.
example: true
dataSlice:
type: object
description: 계정 데이터의 슬라이스를 요청합니다.
properties:
length:
type: integer
description: 반환할 바이트 수입니다.
example: 10
offset:
type: integer
description: 읽기 시작할 바이트 오프셋입니다.
example: 0
encoding:
type: string
description: 계정 데이터의 인코딩 형식입니다.
enum:
- base58
- base64
- base64+zstd
- jsonParsed
example: jsonParsed
limit:
type: integer
description: 요청당 반환할 최대 토큰 계수(1-10,000)입니다.
minimum: 1
maximum: 10000
example: 1000
paginationKey:
type: string
description: >-
후속 페이지를 가져오기 위한 base-58로 인코딩된 페이지네이션 커서입니다. 이전
응답에서 paginationKey를 사용하십시오.
example: 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM
changedSinceSlot:
type: integer
description: 이 슬롯 이후에 수정된 토큰 계정만 반환합니다. 점진적 포트폴리오 업데이트에 유용합니다.
example: 12345678
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:
oneOf:
- $ref: >-
#/components/schemas/TokenAccountsByOwnerV2ResultDirect
title: without withContext
- type: object
title: with withContext
description: 요청 옵션에서 `withContext`가 `true`일 경우 래핑된 결과입니다.
required:
- context
- value
properties:
context:
type: object
description: 노드 응답에 대한 스냅샷 메타데이터(슬롯 일관성, 디버깅용)입니다.
properties:
slot:
type: integer
description: 노드가 이 응답을 작성한 슬롯입니다.
example: 341197933
apiVersion:
type: string
description: 사용 가능한 경우 RPC API 버전입니다.
example: 2.0.15
value:
$ref: '#/components/schemas/TokenAccountsByOwnerV2Page'
example:
jsonrpc: '2.0'
id: '1'
result:
value:
- pubkey: BGocb4GEpbTFm8UFV2VsDSaBXHELPfAXrvd4vtt8QWrA
account:
lamports: 2039280
owner: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
data:
program: spl-token
parsed:
info:
isNative: false
mint: 2cHr7QS3xfuSV8wdxo3ztuF4xbiarF6Nrgx3qpx3HzXR
owner: A1TMhSGzQxMr1TboBKtgixKz1sS6REASMxPo1qsyTSJd
state: initialized
tokenAmount:
amount: '420000000000000'
decimals: 6
uiAmount: 420000000
uiAmountString: '420000000'
space: 165
executable: false
rentEpoch: 18446744073709552000
space: 165
paginationKey: 8WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM
'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:
TokenAccountsByOwnerV2ResultDirect:
type: object
description: >-
`withContext`가 false이거나 생략되었을 때의 페이지네이션된 토큰 계정입니다. 계정 목록이 객체가 아닌 배열로
`result.value`에 있는 익숙한 형태와 일치합니다.
properties:
value:
type: array
description: 현재 페이지의 토큰 계정입니다.
items:
$ref: '#/components/schemas/TokenAccountByOwnerV2Entry'
paginationKey:
type: string
description: >-
다음 페이지를 위한 페이지네이션 커서입니다. 토큰 계정이 반환되지 않을 때만 null입니다 (페이지네이션의 끝).
필터링으로 인해 제한보다 적은 계정이 반환될 수 있지만 이는 페이지네이션의 끝을 나타내지 않습니다.
example: 8WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM
nullable: true
TokenAccountsByOwnerV2Page:
type: object
description: >-
`withContext`가 true일 때의 페이지네이션된 토큰 계정입니다. `result.context`와 함께
`result.value` 하에 `accounts`와 `paginationKey`를 포함합니다.
properties:
accounts:
type: array
description: 현재 페이지의 토큰 계정입니다.
items:
$ref: '#/components/schemas/TokenAccountByOwnerV2Entry'
paginationKey:
type: string
description: >-
다음 페이지를 위한 페이지네이션 커서입니다. 토큰 계정이 반환되지 않을 때만 null입니다 (페이지네이션의 끝).
필터링으로 인해 제한보다 적은 계정이 반환될 수 있지만 이는 페이지네이션의 끝을 나타내지 않습니다.
example: 8WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM
nullable: true
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'
TokenAccountByOwnerV2Entry:
type: object
properties:
pubkey:
type: string
description: Base-58로 인코딩된 문자열의 계정 퍼블릭 키입니다.
example: BGocb4GEpbTFm8UFV2VsDSaBXHELPfAXrvd4vtt8QWrA
account:
type: object
description: 토큰 계정 세부 사항입니다.
properties:
lamports:
type: integer
description: 계정에 할당된 lamports 수입니다.
example: 2039280
owner:
type: string
description: 이 계정이 할당된 프로그램의 퍼블릭 키입니다.
example: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
data:
type: object
description: 계정과 관련된 토큰 상태 데이터입니다.
properties:
program:
type: string
description: 프로그램 이름입니다.
example: spl-token
parsed:
type: object
description: 구문 분석된 토큰 데이터입니다.
properties:
info:
type: object
description: 토큰 계정 정보입니다.
properties:
isNative:
type: boolean
description: 계정이 네이티브 SOL을 보유하고 있는지 여부를 나타냅니다.
example: false
mint:
type: string
description: 토큰 민트의 퍼블릭 키입니다.
example: 2cHr7QS3xfuSV8wdxo3ztuF4xbiarF6Nrgx3qpx3HzXR
owner:
type: string
description: 계정 소유자의 퍼블릭 키입니다.
example: A1TMhSGzQxMr1TboBKtgixKz1sS6REASMxPo1qsyTSJd
state:
type: string
description: 토큰 계정 상태입니다.
example: initialized
tokenAmount:
type: object
description: 토큰 양의 세부 사항입니다.
properties:
amount:
type: string
description: 소수점 없는 원시 잔액입니다.
example: '420000000000000'
decimals:
type: integer
description: 소수점의 수입니다.
example: 6
uiAmount:
type: number
description: 사용자 친화적 형식의 잔액입니다.
example: 420000000
uiAmountString:
type: string
description: 문자열로 된 잔액입니다.
example: '420000000'
space:
type: integer
description: 계정에 할당된 공간입니다.
example: 165
executable:
type: boolean
description: 계정에 프로그램이 포함되어 있는지 여부를 나타냅니다.
example: false
rentEpoch:
type: integer
description: 계정이 다음에 임대료를 지불해야 하는 에포크입니다.
example: 18446744073709552000
space:
type: integer
description: 계정의 데이터 크기입니다.
example: 165
securitySchemes:
ApiKeyQuery:
type: apiKey
in: query
name: api-key
description: >-
Helius API 키입니다. [대시보드](https://dashboard.helius.dev/api-keys)에서 무료로 받을
수 있습니다.
````