> ## 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`エンコーディングでは、トークン数量にリクエストしたポジション時点での各ミントの小数点以下桁数が使用されるため、残高にはその時点でウォレットが保有していた数量が反映されます。

履歴は、エポック1030の開始時点の状態であるスロット444,959,999（2026年9月7日）以降で利用できます。

`getHistoricalTokenAccountsByOwner`は、Businessプラン以上のmainnetで利用でき、ベータ期間中は呼び出しごとに0クレジットです。料金は変更される可能性があります。

## getTokenAccountsByOwnerとの違い

* **ミントまたはプログラムのフィルターは任意です。** フィルターを指定しない場合、ウォレットが所有していたすべてのトークンアカウントを取得します。結果を絞り込むには、設定オブジェクト（第3パラメーター）で`mint`または`programId`のいずれか一方を設定します。両方は設定できません。
* **第2パラメーターはクエリオブジェクトです。** ミントやプログラムのフィルターではなく、履歴内のポジションを選択します。
* **`result.value`はオブジェクトです。** 配列ではなく、`accounts`と`paginationKey`を含みます。

## 履歴内のポジションを選択する

第2パラメーターはクエリオブジェクトです。

* **省略または`{}`**：リクエストしたコミットメントを上限とする、インデックス済みの最新スロットです。
* **`{ "slot": 445000000 }`**：スロット445,000,000の終了時点です。
* **`{ "slot": 445000000, "transactionIndex": 10 }`**：そのスロット内のインデックス10のトランザクションが実行された直後です。

ポジションの仕組みについては、[履歴アカウントガイド](https://www.helius.dev/docs/ja/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`と、`<mint>:<tokenAccount>`形式のカーソルである`value.paginationKey`を返します。`null`になるまで、次のリクエストに渡してください。

> [!WARNING]
>
> ページが短い場合や空の場合でも、`paginationKey`が含まれることがあります。末尾に到達したことを示すのは、`null`の`paginationKey`のみです。

ページネーションする際は、必ず`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のmainnetまたはGatekeeperエンドポイントを呼び出してください。このメソッドはdevnetでは利用できません |

## 関連メソッド

> [card] [Historical Accounts Guide](https://www.helius.dev/docs/ja/rpc/historical-accounts.md)
>
> 履歴アカウントメソッドにおけるポジション、対応範囲、lastUpdatedAtの仕組み

> [card] [getHistoricalAccountInfo](https://www.helius.dev/docs/ja/api-reference/rpc/http/gethistoricalaccountinfo.md)
>
> 過去のスロット時点における単一のアカウントを読み取ります

> [card] [getTransactionsForAddress](https://www.helius.dev/docs/ja/rpc/gettransactionsforaddress.md)
>
> 調査するトランザクションのスロットとtransactionIndexを検索します

> [card] [getTokenAccountsByOwnerV2](https://www.helius.dev/docs/ja/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から取得した、`&lt;mint&gt;:&lt;tokenAccount&gt;`形式のカーソルです。mintも設定する場合、カーソルのミントがそれと一致する必要があります。

**commitment** `string` (default: finalized)

コミットメントレベルです。processedはサポートされていません。

* `finalized`
* `confirmed`

**minContextSlot** `number`

リクエストを評価できる最小スロットです。


## OpenAPI

````yaml ja/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 メソッドは、デフォルトですべてのトークンアカウントを返します。設定オブジェクトで mint
        またはトークンの programId のいずれかを指定すると、結果を絞り込めます。


        結果は mint、次にトークンアカウントアドレスの順に並びます。ページが短いか空でも 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: この mint のトークンアカウントのみを返します。programId と併用できません。
                            example: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
                          programId:
                            type: string
                            description: このトークンプログラムが所有するトークンアカウントのみを返します。mint と併用できません。
                            enum:
                              - TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
                              - TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb
                            example: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
                          encoding:
                            type: string
                            description: >-
                              アカウントデータのエンコーディング形式です。jsonParsed
                              では、トークン数量に指定された位置での mint の小数桁数が使用されます。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>:<tokenAccount>` です。mint も設定する場合、カーソルの 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: このページのトークンアカウントです。mint、次にトークンアカウントアドレスの順に並びます。
                            items:
                              $ref: '#/components/schemas/HistoricalKeyedAccount'
                          paginationKey:
                            oneOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              次のページのカーソルです。形式は `<mint>:<tokenAccount>`
                              で、すべてのアカウントが返されると null になります。paginationKey
                              がある短いページまたは空のページは、末尾に到達したことではなく、スキャンが途中で停止したことを示します。
                            example: >-
                              11112zAgXhc6hGfdfr5anSY91mq7Cs4HHpSVEQc4ASG:EKyGnXReqmmXyqBHmMjV2CKCLafJS47xyhXXZ5WuFMxD
        '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:
    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: >-
            最後に書き込まれたスロットです。値が 444959999 で transactionIndex が null
            の場合、履歴の収集開始以降、アカウントが変更されていないことを示します。
          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.