Comment récupérer l'historique des transactions du portefeuille Solana

L’API Wallet est en version bêta. Les points de terminaison et les formats de réponse peuvent changer.

Aperçu

Le point de terminaison de l’historique des transactions récupère l’historique complet des transactions d’un portefeuille Solana en utilisant l’API Enhanced Transactions. Il renvoie des transactions analysées et lisibles par l’homme avec des modifications de solde pour chaque transaction, dans l’ordre inverse chronologique (la plus récente d’abord). Le point de terminaison renvoie jusqu’à 100 transactions par demande, donc la pagination est manuelle. Utilisez le paramètre before avec pagination.nextCursor pour récupérer la page suivante, et lisez pagination.hasMore pour savoir quand plus de résultats sont disponibles. Chaque demande est un appel API unique et coûte 100 crédits. Le paramètre tokenAccounts contrôle si les transactions impliquant des comptes de jetons détenus par le portefeuille sont incluses :

balanceChanged (recommandé) : inclut les transactions qui ont modifié les soldes des comptes de jetons, filtrant le spam.
none : uniquement les interactions directes avec le portefeuille.
all : toutes les transactions de comptes de jetons, y compris le spam.

Le filtre tokenAccounts repose sur le champ owner dans les métadonnées du solde des jetons, qui n’était pas disponible avant le slot 111,491,819 (~décembre 2022). Les transactions impliquant des comptes de jetons actifs avant ce slot peuvent manquer. Voir le tutoriel getTransactionsForAddress pour une solution de contournement.

Quand l’utiliser

Utilisez l’API de l’historique des transactions lorsque vous avez besoin de :

Afficher un flux de transactions : montrer aux utilisateurs leur historique complet de transactions.
Calculer le PnL : suivre les gains et les pertes sur toutes les transactions.
Impôts et comptabilité : générer des rapports de transaction complets pour la déclaration fiscale.
Analyse de portefeuille : analyser les modèles de trading et l’activité.
Trails d’audit : maintenir des enregistrements complets de l’activité du portefeuille.
Reconstruction de solde : reconstruire les soldes actuels à partir des données historiques.

Démarrage rapide

Requête d’historique de base

Obtenez les transactions les plus récentes avec des modifications de solde :

JavaScript
Python
cURL

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");

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")

curl "https://api.helius.xyz/v1/wallet/86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY/history?api-key=YOUR_API_KEY"

Pagination pour l’historique complet

Récupérez toutes les transactions en utilisant la pagination avec le paramètre before :

JavaScript
Python

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");

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")

Paramètres de requête

Paramètre	Type	Par défaut	Description
`limit`	entier	100	Nombre maximum de transactions par demande (1-100)
`before`	chaîne	-	Récupérer les transactions avant cette signature (utiliser `pagination.nextCursor` à partir de la réponse précédente)
`after`	chaîne	-	Récupérer les transactions après cette signature (pour la pagination en ordre croissant)
`type`	chaîne	-	Filtrer par type de transaction (par exemple, SWAP, TRANSFER, NFT_SALE, TOKEN_MINT)
`tokenAccounts`	chaîne	balanceChanged	Filtrer les transactions impliquant des comptes de jetons : `none`, `balanceChanged` (recommandé), ou `all`

Types de transactions disponibles

Le paramètre type prend en charge le filtrage par ces types de transactions : 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

Exemples de filtres

Filtrer par type
Filtre des comptes de jetons
Filtres combinés

// Get only SWAP transactions
const url = `https://api.helius.xyz/v1/wallet/${address}/history?api-key=YOUR_API_KEY&type=SWAP`;

// 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`;

// 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`;

Format de réponse

{
  "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"
  }
}

Remarques sur les champs

timestamp : secondes Unix. Peut être null pour les transactions très récentes qui n’ont pas encore été entièrement traitées.
error : null pour les transactions réussies ; une valeur d’erreur pour les échecs. Les transactions échouées engendrent toujours des frais.
balanceChanges : comment les avoirs du portefeuille ont changé lors de la transaction — un amount positif concerne les jetons reçus, un amount négatif concerne les jetons envoyés ou dépensés.
mint (dans balanceChanges) : adresse de frappe de jeton, ou "SOL" pour SOL natif.
amount (dans balanceChanges) : lisible par l’homme, déjà divisé par decimals — -0.05 signifie −0.05 SOL, pas −0.05 lamports. Ce point de terminaison n’inclut pas de champ amountRaw brut.

Exemple de modifications de solde

// 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 }
  ]
}

Cas d’utilisation

Calculer le volume total des transactions

Additionner tous les transferts pour obtenir le volume des transactions :

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
);

Générer un rapport fiscal

Créer un rapport de transaction pour la déclaration fiscale :

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);

Suivre les transactions échouées

Trouver toutes les transactions échouées pour comprendre les erreurs :

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;
};

Reconstruire un solde historique

Calculer quel était le solde à un moment donné :

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
);

Pour le solde exact d’un jeton à un moment donné, le point de terminaison Historical Balance le lit directement à partir des soldes post-chaîne au lieu de sommer les changements côté client.

Analyser les frais de transaction

Calculer le total des frais payés :

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
  };
};

Meilleures pratiques

Utiliser la pagination pour un historique complet. Certains portefeuilles ont des centaines de milliers de transactions ; paginer toujours lors de leur récupération.
Mettre en cache les données historiques. Les transactions historiques ne changent jamais. Les mettre en cache localement et ne récupérer que les nouvelles transactions.
Gérer les transactions échouées. Vérifier le champ error pour distinguer les transactions réussies des échouées. Les transactions échouées engendrent toujours des frais.
Utiliser les horodatages pour le filtrage des dates. Les horodatages sont en secondes Unix. Convertir en dates locales pour l’affichage et le filtrage.

Erreurs communes

Code d’erreur	Description	Solution
400	Format d’adresse de portefeuille invalide	Vérifier que l’adresse est une adresse Solana base58 valide
401	Clé API manquante ou invalide	Vérifier que votre clé API est incluse dans la demande
429	Limite de fréquence atteinte	Réduire la fréquence des demandes ou améliorer votre plan

Prochaines étapes

Transferts de jetons

Une vue uniquement transferts avec informations sur l’expéditeur/le destinataire — plus simple que l’historique complet.

Aperçu de l'API Wallet

Tous les points de terminaison de l’API Wallet et les conventions partagées.

Référence API

Schémas de demande et de réponse pour l’historique des transactions.

Commencer

Diffusion de données et écoute d'événements

API de données et RPC

Trading

Envoyer des transactions

Wallet en tant que service

Confidentialité

Ressources

Comment récupérer l'historique des transactions du portefeuille Solana

Aperçu

Quand l’utiliser

Démarrage rapide

Requête d’historique de base

Paramètres de requête

Types de transactions disponibles

Exemples de filtres

Format de réponse

Remarques sur les champs

Exemple de modifications de solde

Cas d’utilisation

Calculer le volume total des transactions

Générer un rapport fiscal

Suivre les transactions échouées

Reconstruire un solde historique

Analyser les frais de transaction

Meilleures pratiques

Erreurs communes

Prochaines étapes

Transferts de jetons

Aperçu de l'API Wallet

Référence API

​Aperçu

​Quand l’utiliser

​Démarrage rapide

​Requête d’historique de base

​Pagination pour l’historique complet

​Paramètres de requête

​Types de transactions disponibles

​Exemples de filtres

​Format de réponse

​Remarques sur les champs

​Exemple de modifications de solde

​Cas d’utilisation

​Calculer le volume total des transactions

​Générer un rapport fiscal

​Suivre les transactions échouées

​Reconstruire un solde historique

​Analyser les frais de transaction

​Meilleures pratiques

​Erreurs communes

​Prochaines étapes

Transferts de jetons

Aperçu de l'API Wallet

Référence API

Aperçu

Quand l’utiliser

Démarrage rapide

Requête d’historique de base

Pagination pour l’historique complet

Paramètres de requête

Types de transactions disponibles

Exemples de filtres

Format de réponse

Remarques sur les champs

Exemple de modifications de solde

Cas d’utilisation

Calculer le volume total des transactions

Générer un rapport fiscal

Suivre les transactions échouées

Reconstruire un solde historique

Analyser les frais de transaction

Meilleures pratiques

Erreurs communes

Prochaines étapes