> ## 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` (オプション)
コンフィグオブジェクト (`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 サポート**: `TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb`を`programId`として、転送手数料、利息付トークンなどの拡張機能を備えたToken-2022アカウントをクエリします。
```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`はこのページのトークンアカウント配列であり、`paginationKey`
は`result`に配置されます。同じフィルタリングと制限が適用されます。
アカウントデータのスライスを要求。
返すバイト数。
読み取りを開始するバイトオフセット。
アカウントデータのエンコード形式。
* `base58`
* `base64`
* `base64+zstd`
* `jsonParsed`
リクエストごとに返されるトークンアカウントの最大数（1〜10,000）。
次のページを取得するためのBase-58エンコードされたページネーションクレデンシャル。前のレスポンスのpaginationKeyを使用。
このスロット番号以降に変更されたトークンアカウントのみを返します。インクリメンタルポートフォリオアップデートに便利です。
## OpenAPI
````yaml ja/openapi/rpc-http/getTokenAccountsByOwnerV2.yaml POST /
openapi: 3.1.0
info:
title: Solana RPC API
version: 1.0.0
description: >-
追加機能を備えたSolanaトークンアカウントの検出APIで、カーソルベースのページネーションとchangedSinceSlotサポートを含み、SPLトークン残高、NFT、および任意のウォレットアドレスに関連するその他のトークン保持を効率的に取得できます。スロットベースのフィルタリングを介して増分更新をサポートします。
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: デブネットRPCエンドポイント
security: []
paths:
/:
post:
tags:
- RPC
summary: getTokenAccountsByOwnerV2
description: >
カーソルベースのページネーションとchangedSinceSlotサポートを含むgetTokenAccountsByOwnerの強化バージョンで、特定のウォレットアドレスが所有する大量のSPLトークンアカウントを効率よく取得できます。スケーラブルなポートフォリオクエリを可能にし、1リクエストあたり最大10,000件のアカウントを取得可能です。changedSinceSlotパラメータにより、特定のブロックチェーンスロット以降に変更されたトークンアカウントのみを取得でき、リアルタイムのポートフォリオトラッキングやウォレットバランスの同期に最適です。ウォレット、ポートフォリオトラッカー、DeFiアプリケーション、および広範なトークンポートフォリオを持つユーザーの包括的なトークン保有データを必要とするサービスにとって必須です。
注意:
ページネーションの終了はトークンアカウントが返されない場合にのみ示されます。APIはフィルタリングのため制限よりも少ないアカウントを返すことがありますが、これはページネーションの終了を示しません。
**withContext**:
構成オブジェクト（エンコーディング、制限などと一緒に）におけるオプションのブール値。`withContext`が`true`の時、RPCは標準のSolanaラップされた形を返します：`result.context`（スナップショットメタデータ、`slot`および通常`apiVersion`を含む）、および`result.value`を`accounts`と`paginationKey`を含むオブジェクトとして返します。`withContext`が`false`または省略された場合、アカウントリストは配列として`result.value`です（従来の`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: >-
base-58でエンコードされた文字列としての、トークン保有を照会するためのアカウントオーナーのSolanaウォレットアドレス（pubkey）。
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`）および`accounts`と`paginationKey`を`result.value`にオブジェクトとしてネストして返します。`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でエンコードされたページネーションカーソル。前の応答からのページネーションキーを使用します。
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: Invalid params
id: '1'
'401':
description: 認証されていない - 無効または欠落しているAPIキー。
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
jsonrpc: '2.0'
error:
code: -32001
message: Unauthorized
id: '1'
'429':
description: リクエストが多すぎます - レート制限を超えました。
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
jsonrpc: '2.0'
error:
code: -32005
message: Too many requests
id: '1'
'500':
description: 内部サーバーエラー - サーバーでエラーが発生しました。
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
jsonrpc: '2.0'
error:
code: -32603
message: Internal error
id: '1'
'503':
description: サービス利用不可 - サービスが一時的に利用できません。
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
jsonrpc: '2.0'
error:
code: -32002
message: Service unavailable
id: '1'
'504':
description: ゲートウェイタイムアウト - リクエストがタイムアウトしました。
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
jsonrpc: '2.0'
error:
code: -32003
message: Gateway timeout
id: '1'
security:
- ApiKeyQuery: []
components:
schemas:
TokenAccountsByOwnerV2ResultDirect:
type: object
description: >-
`withContext`がfalseまたは省略されている場合のページネーションされたトークンアカウント。アカウントリストが配列として`result.value`である一般的な形に一致します（`accounts`の下にネストされていません）。
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でエンコードされたアカウントのPubkey。
example: BGocb4GEpbTFm8UFV2VsDSaBXHELPfAXrvd4vtt8QWrA
account:
type: object
description: トークンアカウントの詳細。
properties:
lamports:
type: integer
description: アカウントに割り当てられたラムポートの数。
example: 2039280
owner:
type: string
description: このアカウントが割り当てられているプログラムのPubkey。
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: トークンミントのPubkey。
example: 2cHr7QS3xfuSV8wdxo3ztuF4xbiarF6Nrgx3qpx3HzXR
owner:
type: string
description: アカウントオーナーのPubkey。
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)から取得できます。
````