> ## 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.

# Рекомендации по работе с TypeScript SDK

> Рекомендуемые паттерны Solana для ИИ-агентов, использующих Helius TypeScript SDK: история транзакций, отправка, пакетная обработка, пагинация и обработка ошибок.

Рекомендации и рекомендуемые паттерны для агентов, использующих [Helius TypeScript SDK](https://github.com/helius-labs/helius-sdk). Инструкции по установке и началу работы см. в [обзоре](/docs/ru/agents/typescript-sdk).

## Рекомендации для агентов

### Используйте `getTransactionsForAddress` вместо двухэтапного поиска

`getTransactionsForAddress` объединяет поиск подписи и получение транзакции в одном вызове с фильтрацией на стороне сервера. Поддерживаются диапазоны времени и слотов, фильтрация по токен-аккаунтам и пагинация.

```typescript theme={"system"}
// GOOD: Single call, server-side filtering
const txs = await helius.getTransactionsForAddress([
  "address",
  {
    transactionDetails: "full",
    limit: 100,
    filters: {
      tokenAccounts: "balanceChanged",
      blockTime: { gte: Math.floor(Date.now() / 1000) - 86400 },
    },
  },
]);

// BAD: Two calls, client-side filtering, no token account support
const sigs = await helius.raw.getSignaturesForAddress(address).send();
const txs = await Promise.all(sigs.map(s => helius.raw.getTransaction(s.signature).send()));
```

### Используйте `sendSmartTransaction` для стандартной отправки

Этот метод автоматически выполняет симуляцию, оценивает количество вычислительных единиц, получает приоритетные комиссии и подтверждает транзакцию. Не создавайте инструкции ComputeBudget вручную — SDK добавляет их автоматически.

```typescript theme={"system"}
const sig = await helius.tx.sendSmartTransaction({
  instructions: [yourInstruction],
  signers: [walletSigner],
  commitment: "confirmed",
  priorityFeeCap: 100_000,   // Optional: cap fees in microlamports/CU
  bufferPct: 0.1,            // 10% compute unit headroom (default)
});
```

### Используйте Helius Sender для минимальной задержки

Для транзакций, критичных ко времени (арбитраж, снайпинг, ликвидации), используйте `sendTransactionWithSender`. Этот метод направляет их через мультирегиональную инфраструктуру Helius и Jito.

```typescript theme={"system"}
const sig = await helius.tx.sendTransactionWithSender({
  instructions: [yourInstruction],
  signers: [walletSigner],
  region: "US_EAST",          // Default, US_SLC, US_EAST, EU_WEST, EU_CENTRAL, EU_NORTH, AP_SINGAPORE, AP_TOKYO
  swqosOnly: true,            // Route through SWQOS only (lower tip requirement)
  pollTimeoutMs: 60_000,
  pollIntervalMs: 2_000,
});
```

### Используйте `getAssetBatch` для нескольких активов

При получении нескольких активов объединяйте их в пакеты. Не вызывайте `getAsset` в цикле.

```typescript theme={"system"}
// GOOD: Single request
const assets = await helius.getAssetBatch({
  ids: ["mint1", "mint2", "mint3"],
  options: { showFungible: true, showCollectionMetadata: true },
});

// BAD: N requests
const assets = await Promise.all(mints.map(id => helius.getAsset({ id })));
```

### Используйте вебхуки или WebSocket вместо опроса

Не опрашивайте `getTransactionsForAddress` в цикле. Используйте вебхуки для уведомлений между серверами или WebSocket для потоковой передачи данных клиенту в реальном времени.

```typescript theme={"system"}
// Webhook: server receives POST on matching transactions
const webhook = await helius.webhooks.create({
  webhookURL: "https://your-server.com/webhook",
  webhookType: "enhanced",
  transactionTypes: ["TRANSFER", "NFT_SALE", "SWAP"],
  accountAddresses: ["address_to_monitor"],
  authHeader: "Bearer your-secret",
});

// WebSocket: stream logs in real-time
const req = await helius.ws.logsNotifications({ mentions: ["address"] });
const stream = await req.subscribe({ abortSignal: controller.signal });
for await (const log of stream) {
  console.log(log);
}
```

## Пагинация

SDK использует разные стратегии пагинации в зависимости от метода.

### На основе токена или курсора (методы RPC V2)

```typescript theme={"system"}
// getTransactionsForAddress uses paginationToken
let paginationToken = null;
const allTxs = [];
do {
  const result = await helius.getTransactionsForAddress([
    "address",
    { limit: 100, paginationToken },
  ]);
  allTxs.push(...result.data);
  paginationToken = result.paginationToken;
} while (paginationToken);

// getProgramAccountsV2 uses paginationKey
let paginationKey = null;
do {
  const result = await helius.getProgramAccountsV2([
    programId,
    { limit: 1000, paginationKey },
  ]);
  // process result.accounts
  paginationKey = result.paginationKey;
} while (paginationKey);
```

### На основе страниц (DAS API)

```typescript theme={"system"}
let page = 1;
const allAssets = [];
while (true) {
  const result = await helius.getAssetsByOwner({ ownerAddress: "...", page, limit: 1000 });
  allAssets.push(...result.items);
  if (result.items.length < 1000) break;
  page++;
}
```

## Фильтр `tokenAccounts`

При запросе `getTransactionsForAddress` фильтр `tokenAccounts` определяет, включать ли активность токен-аккаунта:

| Значение | Поведение | Когда использовать |
| - | - | - |
| не указано / `"none"` | Только транзакции, непосредственно связанные с адресом | Вас интересуют только переводы SOL и вызовы программ |
| `"balanceChanged"` | Также включает токен-транзакции, изменившие баланс | **Рекомендуется для большинства агентов** — показывает отправку и получение токенов без лишнего шума |
| `"all"` | Включает все транзакции токен-аккаунта | Вам нужна полная история операций с токенами (может вернуть много результатов) |

## `changedSinceSlot` — инкрементальное получение аккаунтов

`changedSinceSlot` возвращает только аккаунты, измененные после указанного слота. Это полезно для синхронизации и индексирования. Поддерживается в `getProgramAccountsV2`, `getTokenAccountsByOwnerV2`, `getAccountInfo`, `getMultipleAccounts`, `getProgramAccounts` и `getTokenAccountsByOwner`.

```typescript theme={"system"}
// First fetch: get all accounts
const baseline = await helius.getProgramAccountsV2([programId, { limit: 10_000 }]);
const lastSlot = currentSlot;

// Later: only get accounts that changed since your last fetch
const updates = await helius.getProgramAccountsV2([
  programId,
  { limit: 10_000, changedSinceSlot: lastSlot },
]);
```

## Распространенные ошибки

1. **`transactionDetails: "full"` не используется по умолчанию** — по умолчанию `getTransactionsForAddress` возвращает только подписи. Укажите `transactionDetails: "full"`, чтобы получить полные данные транзакций.

2. **Не добавляйте инструкции ComputeBudget при использовании `sendSmartTransaction`** — SDK добавляет их автоматически. Если вы добавите собственные инструкции, возникнут дубликаты и транзакция завершится с ошибкой.

3. **Приоритетные комиссии указываются в микролампортах на вычислительную единицу** — не в лампортах. Значения из `getPriorityFeeEstimate` уже представлены в единицах, необходимых для `SetComputeUnitPrice`.

4. **Пагинация DAS начинается с 1** — первая страница — `page: 1`, а не `page: 0`.

5. **`blockTime` указывается в секундах Unix, а не в миллисекундах** — при фильтрации по `blockTime` используйте `Math.floor(Date.now() / 1000)`.

6. **`getAsset` по умолчанию скрывает взаимозаменяемые токены** — чтобы включить их, передайте `options: { showFungible: true }`.

7. **Потоки WebSocket необходимо закрывать** — всегда используйте сигнал AbortController и по завершении вызывайте `helius.ws.close()`, чтобы избежать утечек соединений.

8. **Указывайте `maxSupportedTransactionVersion: 1` при получении транзакций.** Иначе `getTransaction`, `getBlock` и `getTransactionsForAddress` с `transactionDetails: "full"` завершаются ошибкой `-32015` для транзакций v1. В транзакциях v1 приоритетная комиссия указана в `message.transactionConfig.priorityFee` как общая сумма в лампортах; инструкции ComputeBudget для поиска отсутствуют. См. раздел [Поддержка транзакций v1](/docs/ru/rpc/transaction-v1).

## Обработка ошибок и повторные попытки

SDK создает встроенные объекты `Error`, в строку сообщения которых включен код состояния HTTP (например, `"API error (429): ..."`). В объекте ошибки нет свойства `.status`, поэтому для определения состояния необходимо анализировать сообщение.

```typescript theme={"system"}
async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      const msg = error instanceof Error ? error.message : "";
      const status = msg.match(/\b(\d{3})\b/)?.[1];
      const retryable = status === "429" || (status && status.startsWith("5"));
      if (!retryable || attempt === maxRetries) throw error;
      await new Promise(r => setTimeout(r, 1000 * 2 ** attempt));
    }
  }
  throw new Error("Unreachable");
}
```

| Состояние | Значение | Действие |
| - | - | - |
| 401 | Недействительный или отсутствующий ключ API | Проверьте ключ API |
| 429 | Превышен лимит запросов или закончились кредиты | Увеличьте интервал и повторите попытку |
| 5xx | Ошибка сервера | Повторите попытку с экспоненциальной задержкой |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.