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

# Как получить историю транзакций кошелька Solana

> Получите полную историю транзакций любого кошелька Solana с изменениями баланса для каждой транзакции — для трекеров портфелей, бухгалтерского учета и аналитики.

<Note>
  Wallet API находится на стадии бета-тестирования. Эндпоинты и форматы ответов могут измениться.
</Note>

## Обзор

Эндпоинт Transaction History получает полную историю транзакций кошелька Solana с помощью Enhanced Transactions API. Он возвращает разобранные транзакции в удобочитаемом формате с изменениями баланса для каждой транзакции в обратном хронологическом порядке (сначала новые).

Эндпоинт возвращает до 100 транзакций на запрос, поэтому пагинацию необходимо выполнять вручную. Чтобы получить следующую страницу, используйте параметр `before` со значением `pagination.nextCursor`. Проверяйте `pagination.hasMore`, чтобы узнать, доступны ли дополнительные результаты. Каждый запрос представляет собой один вызов API и расходует 100 кредитов.

Параметр `tokenAccounts` определяет, включать ли транзакции, связанные с принадлежащими кошельку аккаунтами токенов:

* `balanceChanged` (рекомендуется): включает транзакции, которые изменили балансы аккаунтов токенов, и отфильтровывает спам.
* `none`: только прямые взаимодействия с кошельком.
* `all`: все транзакции аккаунтов токенов, включая спам.

<Warning>
  Фильтр `tokenAccounts` использует поле `owner` в метаданных баланса токенов, которое было недоступно до слота 111 491 819 (примерно до декабря 2022 года). Транзакции с аккаунтами токенов, активными до этого слота, могут отсутствовать. Обходное решение описано в [руководстве по getTransactionsForAddress](/docs/ru/rpc/gettransactionsforaddress#ограничения-и-особые-случаи).
</Warning>

## Когда это использовать

Используйте Transaction History API, если вам нужно:

* **Отобразить ленту транзакций**: покажите пользователям полную историю их транзакций.
* **Рассчитать PnL**: отслеживайте прибыль и убытки по всем транзакциям.
* **Налоговый и бухгалтерский учет**: создавайте полные отчеты о транзакциях для подачи налоговой декларации.
* **Аналитика портфеля**: анализируйте торговые модели и активность.
* **Аудиторские журналы**: храните полные записи об активности кошелька.
* **Восстановление баланса**: восстанавливайте текущие балансы по историческим данным.

## Быстрый старт

### Базовый запрос истории

Получите последние транзакции с изменениями баланса:

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={"system"}
    const getTransactionHistory = async (address) => {
      const url = `https://api.helius.xyz/v1/wallet/${address}/history?api-key=YOUR_API_KEY`;

      const response = await fetch(url);
      if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
      }

      const data = await response.json();

      console.log(`Found ${data.data.length} transactions`);

      // Display recent transactions
      data.data.forEach(tx => {
        const date = new Date(tx.timestamp * 1000).toLocaleString();
        const status = tx.error ? 'Failed' : 'Success';

        console.log(`\n${status} - ${date}`);
        console.log(`Signature: ${tx.signature.slice(0, 20)}...`);
        console.log(`Fee: ${tx.fee} SOL`);

        // Show balance changes
        tx.balanceChanges.forEach(change => {
          const sign = change.amount > 0 ? '+' : '';
          console.log(`  ${sign}${change.amount} ${change.mint === 'SOL' ? 'SOL' : change.mint.slice(0, 8)}...`);
        });
      });

      return data;
    };

    getTransactionHistory("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY");
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    import requests
    from datetime import datetime

    def get_transaction_history(address: str):
        url = f"https://api.helius.xyz/v1/wallet/{address}/history"
        headers = {"X-Api-Key": "YOUR_API_KEY"}

        response = requests.get(url, headers=headers)
        response.raise_for_status()

        data = response.json()

        print(f"Found {len(data['data'])} transactions")

        # Display recent transactions
        for tx in data['data']:
            date = datetime.fromtimestamp(tx['timestamp']).strftime('%Y-%m-%d %H:%M:%S')
            status = 'Failed' if tx.get('error') else 'Success'

            print(f"\n{status} - {date}")
            print(f"Signature: {tx['signature'][:20]}...")
            print(f"Fee: {tx['fee']} SOL")

            # Show balance changes
            for change in tx['balanceChanges']:
                sign = '+' if change['amount'] > 0 else ''
                mint_display = 'SOL' if change['mint'] == 'SOL' else change['mint'][:8] + '...'
                print(f"  {sign}{change['amount']} {mint_display}")

        return data

    get_transaction_history("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY")
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={"system"}
    curl "https://api.helius.xyz/v1/wallet/86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY/history?api-key=YOUR_API_KEY"
    ```
  </Tab>
</Tabs>

### Пагинация для получения полной истории

Получите все транзакции с помощью пагинации и параметра `before`:

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={"system"}
    const getAllTransactionHistory = async (address) => {
      let allTransactions = [];
      let before = null;

      do {
        const url = before
          ? `https://api.helius.xyz/v1/wallet/${address}/history?api-key=YOUR_API_KEY&before=${before}`
          : `https://api.helius.xyz/v1/wallet/${address}/history?api-key=YOUR_API_KEY`;

        const response = await fetch(url);
        const data = await response.json();

        allTransactions = allTransactions.concat(data.data);
        before = data.pagination.hasMore ? data.pagination.nextCursor : null;

        console.log(`Fetched ${allTransactions.length} transactions so far...`);

      } while (before);

      console.log(`\nTotal transactions: ${allTransactions.length}`);
      return allTransactions;
    };

    getAllTransactionHistory("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY");
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    def get_all_transaction_history(address: str):
        all_transactions = []
        before = None

        while True:
            url = f"https://api.helius.xyz/v1/wallet/{address}/history"
            params = {"api-key": "YOUR_API_KEY"}

            if before:
                params["before"] = before

            response = requests.get(url, params=params, headers={"X-Api-Key": "YOUR_API_KEY"})
            response.raise_for_status()

            data = response.json()
            all_transactions.extend(data['data'])

            print(f"Fetched {len(all_transactions)} transactions so far...")

            if not data['pagination']['hasMore']:
                break

            before = data['pagination']['nextCursor']

        print(f"\nTotal transactions: {len(all_transactions)}")
        return all_transactions

    get_all_transaction_history("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY")
    ```
  </Tab>
</Tabs>

## Параметры запроса

| Параметр | Тип | Значение по умолчанию | Описание |
| - | - | - | - |
| `limit` | целое число | 100 | Максимальное количество транзакций на запрос (1–100) |
| `before` | строка | - | Получить транзакции до этой подписи (используйте `pagination.nextCursor` из предыдущего ответа) |
| `after` | строка | - | Получить транзакции после этой подписи (для пагинации в порядке возрастания) |
| `type` | строка | - | Фильтровать по типу транзакции (например, SWAP, TRANSFER, NFT\_SALE, TOKEN\_MINT) |
| `tokenAccounts` | строка | balanceChanged | Фильтровать транзакции, связанные с аккаунтами токенов: `none`, `balanceChanged` (рекомендуется) или `all` |

### Доступные типы транзакций

Параметр `type` поддерживает фильтрацию по следующим типам транзакций:

`SWAP`, `TRANSFER`, `NFT_SALE`, `NFT_BID`, `NFT_LISTING`, `NFT_MINT`, `NFT_CANCEL_LISTING`, `TOKEN_MINT`, `BURN`, `COMPRESSED_NFT_MINT`, `COMPRESSED_NFT_TRANSFER`, `COMPRESSED_NFT_BURN`, `CREATE_STORE`, `WHITELIST_CREATOR`, `ADD_TO_WHITELIST`, `REMOVE_FROM_WHITELIST`, `AUCTION_MANAGER_CLAIM_BID`, `EMPTY_PAYMENT_ACCOUNT`, `UPDATE_PRIMARY_SALE_METADATA`, `ADD_TOKEN_TO_VAULT`, `ACTIVATE_VAULT`, `INIT_VAULT`, `INIT_BANK`, `INIT_STAKE`, `MERGE_STAKE`, `SPLIT_STAKE`, `CREATE_AUCTION_MANAGER`, `START_AUCTION`, `CREATE_AUCTION_MANAGER_V2`, `UPDATE_EXTERNAL_PRICE_ACCOUNT`, `EXECUTE_TRANSACTION`

### Примеры фильтров

<Tabs>
  <Tab title="Filter by Type">
    ```javascript theme={"system"}
    // Get only SWAP transactions
    const url = `https://api.helius.xyz/v1/wallet/${address}/history?api-key=YOUR_API_KEY&type=SWAP`;
    ```
  </Tab>

  <Tab title="Token Accounts Filter">
    ```javascript theme={"system"}
    // Exclude spam by only including transactions that changed token balances
    const url = `https://api.helius.xyz/v1/wallet/${address}/history?api-key=YOUR_API_KEY&tokenAccounts=balanceChanged`;

    // Only show direct wallet interactions
    const url = `https://api.helius.xyz/v1/wallet/${address}/history?api-key=YOUR_API_KEY&tokenAccounts=none`;
    ```
  </Tab>

  <Tab title="Combined Filters">
    ```javascript theme={"system"}
    // Get only NFT sales that changed balances
    const url = `https://api.helius.xyz/v1/wallet/${address}/history?api-key=YOUR_API_KEY&type=NFT_SALE&tokenAccounts=balanceChanged`;
    ```
  </Tab>
</Tabs>

## Формат ответа

```json theme={"system"}
{
  "data": [
    {
      "signature": "5wHu1qwD7Jsj3xqWjdSEJmYr3Q5f5RjXqjqQJ7jqEj7jqEj7jqEj7jqEj7jqEj7jqE",
      "timestamp": 1704067200,
      "slot": 250000000,
      "fee": 0.000005,
      "feePayer": "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY",
      "error": null,
      "balanceChanges": [
        {
          "mint": "So11111111111111111111111111111111111111111",
          "amount": -0.05,
          "decimals": 9
        },
        {
          "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
          "amount": 50.0,
          "decimals": 6
        }
      ]
    }
  ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "5wHu1qwD7Jsj3xqWjdSEJmYr3Q5f5RjXqjqQJ7jqEj7jqEj7jqEj7jqEj7jqEj7jqE"
  }
}
```

### Примечания к полям

* **`timestamp`**: время Unix в секундах. Для совсем недавних транзакций, которые еще не были полностью обработаны, значением может быть `null`.
* **`error`**: `null` для успешных транзакций; значение ошибки для неудачных. За неудачные транзакции комиссия также взимается.
* **`balanceChanges`**: изменение активов кошелька в результате транзакции — положительное значение `amount` означает получение токенов, а отрицательное — отправку или расходование токенов.
* **`mint`** (в `balanceChanges`): адрес минта токена или `"SOL"` для нативного SOL.
* **`amount`** (в `balanceChanges`): **удобочитаемое значение**, уже разделенное на `decimals` — `-0.05` означает −0,05 SOL, а не −0,05 лампорта. Этот эндпоинт не включает необработанное поле `amountRaw`.

#### Пример изменений баланса

```javascript theme={"system"}
// Swap: Sold 0.05 SOL, received 5 USDC
{
  "balanceChanges": [
    { "mint": "SOL", "amount": -0.05, "decimals": 9 },
    { "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "amount": 5.0, "decimals": 6 }
  ]
}

// Simple transfer: Sent 10 USDC
{
  "balanceChanges": [
    { "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "amount": -10.0, "decimals": 6 }
  ]
}
```

## Варианты использования

### Расчет общего объема торговли

Суммируйте все переводы, чтобы получить объем торговли:

```javascript theme={"system"}
const calculateTradingVolume = async (address, tokenMint) => {
  const transactions = await getAllTransactionHistory(address);

  let totalVolume = 0;

  transactions.forEach(tx => {
    tx.balanceChanges.forEach(change => {
      if (change.mint === tokenMint) {
        totalVolume += Math.abs(change.amount);
      }
    });
  });

  console.log(`Total ${tokenMint} volume: ${totalVolume}`);
  return totalVolume;
};

// Example: Calculate total USDC volume
calculateTradingVolume(
  "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY",
  "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" // USDC
);
```

### Создание налогового отчета

Создайте отчет о транзакциях для подачи налоговой декларации:

```javascript theme={"system"}
const generateTaxReport = async (address, year) => {
  const transactions = await getAllTransactionHistory(address);

  const startDate = new Date(`${year}-01-01`).getTime() / 1000;
  // Set to end of December 31st (23:59:59.999) to include all transactions from that day
  const endDate = new Date(`${year}-12-31T23:59:59.999Z`).getTime() / 1000;

  const taxableTransactions = transactions
    .filter(tx => tx.timestamp >= startDate && tx.timestamp <= endDate)
    .map(tx => ({
      date: new Date(tx.timestamp * 1000).toISOString(),
      signature: tx.signature,
      fee: tx.fee,
      balanceChanges: tx.balanceChanges,
      explorerUrl: `https://orbmarkets.io/tx/${tx.signature}`
    }));

  console.log(`Found ${taxableTransactions.length} transactions in ${year}`);

  // Export as JSON
  const report = {
    address,
    year,
    transactionCount: taxableTransactions.length,
    transactions: taxableTransactions
  };

  console.log(JSON.stringify(report, null, 2));
  return report;
};

generateTaxReport("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY", 2024);
```

### Отслеживание неудачных транзакций

Найдите все неудачные транзакции, чтобы разобраться в ошибках:

```javascript theme={"system"}
const getFailedTransactions = async (address) => {
  const data = await getTransactionHistory(address);

  const failed = data.data.filter(tx => tx.error !== null);

  console.log(`Found ${failed.length} failed transactions`);

  failed.forEach(tx => {
    const date = new Date(tx.timestamp * 1000).toLocaleString();
    console.log(`\n${date}`);
    console.log(`Signature: ${tx.signature}`);
    console.log(`Error: ${tx.error}`);
    console.log(`Fee Paid: ${tx.fee} SOL`);
  });

  return failed;
};
```

### Восстановление исторического баланса

Рассчитайте баланс на определенный момент времени:

```javascript theme={"system"}
const getHistoricalBalance = async (address, targetTimestamp) => {
  const transactions = await getAllTransactionHistory(address);

  // Filter to transactions before target date
  const relevantTxs = transactions.filter(tx => tx.timestamp <= targetTimestamp);

  // Sum all balance changes
  const balances = {};

  relevantTxs.forEach(tx => {
    tx.balanceChanges.forEach(change => {
      if (!balances[change.mint]) {
        balances[change.mint] = 0;
      }
      balances[change.mint] += change.amount;
    });
  });

  console.log(`Historical balances as of ${new Date(targetTimestamp * 1000).toLocaleString()}:`);
  Object.entries(balances).forEach(([mint, balance]) => {
    console.log(`${mint}: ${balance}`);
  });

  return balances;
};

// Example: Get balances on Jan 1, 2024
getHistoricalBalance(
  "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY",
  new Date("2024-01-01").getTime() / 1000
);
```

Чтобы получить точный баланс одного токена на определенный момент времени, используйте эндпоинт [Historical Balance](/docs/ru/wallet-api/balance-at). Он считывает значение непосредственно из итоговых балансов в блокчейне, а не суммирует изменения на стороне клиента.

### Анализ комиссий за транзакции

Рассчитайте общую сумму уплаченных комиссий:

```javascript theme={"system"}
const analyzeFees = async (address) => {
  const transactions = await getAllTransactionHistory(address);

  const totalFees = transactions.reduce((sum, tx) => sum + tx.fee, 0);
  const avgFee = totalFees / transactions.length;

  const successfulTxs = transactions.filter(tx => !tx.error);
  const failedTxs = transactions.filter(tx => tx.error);

  const wastedFees = failedTxs.reduce((sum, tx) => sum + tx.fee, 0);

  console.log(`Total Transactions: ${transactions.length}`);
  console.log(`Successful: ${successfulTxs.length}`);
  console.log(`Failed: ${failedTxs.length}`);
  console.log(`Total Fees Paid: ${totalFees.toFixed(6)} SOL`);
  console.log(`Average Fee: ${avgFee.toFixed(6)} SOL`);
  console.log(`Wasted on Failed Txs: ${wastedFees.toFixed(6)} SOL`);

  return {
    totalFees,
    avgFee,
    wastedFees,
    successRate: (successfulTxs.length / transactions.length) * 100
  };
};
```

## Рекомендации

* **Используйте пагинацию для получения полной истории.** Некоторые кошельки содержат сотни тысяч транзакций. При получении всех транзакций всегда используйте пагинацию.
* **Кэшируйте исторические данные.** Исторические транзакции никогда не меняются. Кэшируйте их локально и получайте только новые транзакции.
* **Обрабатывайте неудачные транзакции.** Проверяйте поле `error`, чтобы отличать успешные транзакции от неудачных. За неудачные транзакции комиссия также взимается.
* **Используйте временные метки для фильтрации по дате.** Временные метки указаны в секундах Unix. Для отображения и фильтрации преобразуйте их в локальные даты.

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

| Код ошибки | Описание | Решение |
| - | - | - |
| 400 | Недопустимый формат адреса кошелька | Убедитесь, что адрес является допустимым адресом Solana в формате base58 |
| 401 | API-ключ отсутствует или недействителен | Убедитесь, что API-ключ включен в запрос |
| 429 | Превышен лимит запросов | Уменьшите частоту запросов или перейдите на более высокий тариф |

## Следующие шаги

<CardGroup cols={3}>
  <Card title="Token Transfers" icon="arrow-right-arrow-left" href="/docs/ru/wallet-api/transfers">
    Представление только переводов с информацией об отправителе и получателе — проще, чем полная история.
  </Card>

  <Card title="Wallet API Overview" icon="wallet" href="/docs/ru/wallet-api/overview">
    Все эндпоинты Wallet API и общие соглашения.
  </Card>

  <Card title="API Reference" icon="code" href="/docs/ru/api-reference/wallet-api/history">
    Схемы запросов и ответов для истории транзакций.
  </Card>
</CardGroup>


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