> ## 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
> getTokenAccountsByOwnerV2 — это улучшенная версия getTokenAccountsByOwner с курсорной пагинацией и обновлениями changedSinceSlot для крупных портфелей токенов Solana.
## Обзор
`getTokenAccountsByOwnerV2` — это улучшенная версия стандартного метода `getTokenAccountsByOwner`, специально разработанная для эффективного запроса портфелей токенов и обработки кошельков с большим количеством токенов. Этот метод поддерживает курсорную пагинацию и инкрементальные обновления.
**Новые возможности V2:**
* **Курсорная пагинация**: настройте лимит от 1 до 10 000 токеновых счетов на запрос
* **Инкрементальные обновления**: используйте `changedSinceSlot`, чтобы получать только недавно изменённые токеновые счета
* **Масштабирование портфеля**: эффективно обрабатывайте кошельки с тысячами токеновых счетов
* **Обратная совместимость**: поддерживаются все существующие параметры и фильтры `getTokenAccountsByOwner`
* **Необязательный `withContext`**: значение `true` добавляет `slot` и `apiVersion` в `result.context`; если параметр не указан или равен `false`, эти поля не включаются
**Требование к фильтру**: в запросе необходимо указать либо `mint` (конкретный токен), либо `programId` (программа SPL Token или 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 (публичный ключ) владельца счёта, токены которого требуется запросить, в виде строки с кодировкой base-58.
Адрес выпуска конкретного токена Solana, позволяющий получить только счета определённого токена или NFT.
Идентификатор конкретной токеновой программы Solana (обычно программы SPL Token), которая создала токеновые счета.
Уровень подтверждения для запроса.
* `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 ru/openapi/rpc-http/getTokenAccountsByOwnerV2.yaml POST /
openapi: 3.1.0
info:
title: Solana RPC API
version: 1.0.0
description: >-
Расширенный API обнаружения токен-аккаунтов Solana с дополнительными
возможностями, включая пагинацию на основе курсора и поддержку
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 тестовой сети Devnet
security: []
paths:
/:
post:
tags:
- RPC
summary: getTokenAccountsByOwnerV2
description: >
Расширенная версия getTokenAccountsByOwner с дополнительными
возможностями, включая пагинацию на основе курсора
и поддержку changedSinceSlot для эффективного получения больших наборов
токен-аккаунтов SPL, принадлежащих
определенному адресу кошелька. Позволяет выполнять масштабируемые
запросы к портфелю с настраиваемым размером страницы до 10 000
аккаунтов на запрос. Параметр changedSinceSlot позволяет получать только
токен-аккаунты, измененные
с определенного слота блокчейна. Это оптимально для отслеживания
портфеля и синхронизации баланса
кошелька в реальном времени. Необходима для кошельков, средств
отслеживания портфелей, приложений DeFi и любых сервисов,
которым требуются полные данные о токеновых активах пользователей с
крупными портфелями токенов.
Примечание. Конец пагинации обозначается только отсутствием возвращенных
токен-аккаунтов. Из-за фильтрации API может вернуть меньше
аккаунтов, чем задано ограничением. Продолжайте пагинацию, пока
paginationKey не получит значение null.
**withContext**: необязательное логическое значение в объекте
конфигурации наряду с encoding, limit и другими параметрами. Когда
`withContext` имеет значение `true`, RPC возвращает стандартную
обернутую структуру Solana: `result.context` (метаданные
снимка, включая `slot` и обычно `apiVersion`) и `result.value` в виде
объекта, содержащего `accounts`
и `paginationKey`. Когда `withContext` имеет значение `false` или не
указано, список аккаунтов находится
в `result.value` в виде массива, как в классическом
`getTokenAccountsByOwner`, а `paginationKey` —
в `result`. Фильтры, ограничения и поведение пагинации не меняются;
отличается только JSON-структура
`result`.
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 (публичный ключ) владельца
аккаунта, токеновые активы которого нужно запросить, в
виде строки, закодированной в base58.
example: A1TMhSGzQxMr1TboBKtgixKz1sS6REASMxPo1qsyTSJd
- type: object
description: >-
Конфигурация фильтра для отбора токен-аккаунтов по
адресу минта или идентификатору программы.
properties:
mint:
type: string
description: >-
Определенный адрес минта токена Solana для
получения только аккаунтов конкретного токена или
NFT.
example: 2cHr7QS3xfuSV8wdxo3ztuF4xbiarF6Nrgx3qpx3HzXR
programId:
type: string
description: >-
Идентификатор определенной токен-программы Solana,
создавшей токен-аккаунты (обычно программа SPL
Token).
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: >-
Курсор пагинации в кодировке base58 для получения
последующих страниц. Используйте 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: без withContext
- type: object
title: с 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.
Содержит `accounts` и `paginationKey` в `result.value`, а также
`result.context`.
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: Публичный ключ аккаунта в виде строки, закодированной в base58.
example: BGocb4GEpbTFm8UFV2VsDSaBXHELPfAXrvd4vtt8QWrA
account:
type: object
description: Сведения о токен-аккаунте.
properties:
lamports:
type: integer
description: Количество лампортов, назначенных аккаунту.
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: >-
Ваш ключ API Helius. Его можно получить бесплатно в [панели
управления](https://dashboard.helius.dev/api-keys).
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.