Comment obtenir tous les transferts de portefeuille Solana

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

Vue d’ensemble

Le point de terminaison des Transferts de Jetons récupère toute l’activité de transfert de jetons pour un portefeuille Solana, y compris les informations détaillées sur l’expéditeur et le destinataire. Contrairement à l’historique complet des transactions, ce point de terminaison se concentre spécifiquement sur les transferts, ce qui le rend idéal pour le suivi des paiements et la surveillance des transferts. Le point de terminaison retourne jusqu’à 100 transferts par demande (50 par défaut). Utilisez le paramètre cursor avec pagination.nextCursor pour récupérer la page suivante, et lisez pagination.hasMore pour savoir quand d’autres résultats sont disponibles.

Quand l’utiliser

Utilisez l’API des Transferts de Jetons lorsque vous devez :

Suivre les paiements : surveiller les paiements entrants pour les processeurs de paiement.
Construire un flux de transferts : afficher un flux d’activité “envoyé/reçu” simple.
Surveiller des jetons spécifiques : suivre les transferts d’un jeton spécifique (p. ex., paiements USDC).
Identifier les contreparties : voir qui a envoyé ou reçu des jetons.
Générer des reçus : créer des reçus de paiement avec les détails de l’expéditeur/destinataire.
Détecter une activité suspecte : surveiller les motifs de transfert inhabituels.

Démarrage rapide

Requête de base des transferts

Obtenez les transferts entrants et sortants récents :

JavaScript
Python
cURL

const getWalletTransfers = async (address) => {
  const url = `https://api.helius.xyz/v1/wallet/${address}/transfers?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} transfers`);

  // Display recent transfers
  data.data.forEach(transfer => {
    const date = new Date(transfer.timestamp * 1000).toLocaleString();
    const direction = transfer.direction === 'in' ? 'Received' : 'Sent';
    const counterparty = transfer.counterparty.slice(0, 8) + '...';

    console.log(`\n${direction} - ${date}`);
    console.log(`Amount: ${transfer.amount} ${transfer.symbol || transfer.mint.slice(0, 8) + '...'}`);
    console.log(`${transfer.direction === 'in' ? 'From' : 'To'}: ${counterparty}`);
    console.log(`Signature: ${transfer.signature.slice(0, 20)}...`);
  });

  return data;
};

getWalletTransfers("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY");

import requests
from datetime import datetime

def get_wallet_transfers(address: str):
    url = f"https://api.helius.xyz/v1/wallet/{address}/transfers"
    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'])} transfers")

    # Display recent transfers
    for transfer in data['data']:
        date = datetime.fromtimestamp(transfer['timestamp']).strftime('%Y-%m-%d %H:%M:%S')
        direction = 'Received' if transfer['direction'] == 'in' else 'Sent'
        counterparty = transfer['counterparty'][:8] + '...'
        symbol = transfer.get('symbol') or transfer['mint'][:8] + '...'

        print(f"\n{direction} - {date}")
        print(f"Amount: {transfer['amount']} {symbol}")
        print(f"{'From' if transfer['direction'] == 'in' else 'To'}: {counterparty}")
        print(f"Signature: {transfer['signature'][:20]}...")

    return data

get_wallet_transfers("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY")

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

Filtrer par direction

Filtrez les résultats côté client pour obtenir uniquement les transferts entrants ou sortants :

Entrants uniquement
Sortants uniquement

const getIncomingTransfers = async (address) => {
  const data = await getWalletTransfers(address);

  const incoming = data.data.filter(t => t.direction === 'in');

  console.log(`Received ${incoming.length} incoming transfers`);

  incoming.forEach(transfer => {
    console.log(`Received ${transfer.amount} ${transfer.symbol} from ${transfer.counterparty.slice(0, 8)}...`);
  });

  return incoming;
};

const getOutgoingTransfers = async (address) => {
  const data = await getWalletTransfers(address);

  const outgoing = data.data.filter(t => t.direction === 'out');

  console.log(`Made ${outgoing.length} outgoing transfers`);

  outgoing.forEach(transfer => {
    console.log(`Sent ${transfer.amount} ${transfer.symbol} to ${transfer.counterparty.slice(0, 8)}...`);
  });

  return outgoing;
};

Paramètres de requête

Paramètre	Type	Défaut	Description
`limit`	entier	50	Nombre maximum de transferts à retourner (1-100)
`cursor`	chaîne	-	Curseur de pagination de la réponse précédente

Format de réponse

{
  "data": [
    {
      "signature": "5wHu1qwD7Jsj3xqWjdSEJmYr3Q5f5RjXqjqQJ7jqEj7jqEj7jqEj7jqEj7jqEj7jqE",
      "timestamp": 1704067200,
      "direction": "in",
      "counterparty": "HXsKP7wrBWaQ8T2Vtjry3Nj3oUgwYcqq9vrHDM12G664",
      "mint": "So11111111111111111111111111111111111111111",
      "symbol": "SOL",
      "amount": 1.5,
      "amountRaw": "1500000000",
      "decimals": 9
    },
    {
      "signature": "4aHu2qwD8Jtj4xqWjdSEJmYr3Q5f5RjXqjqQJ7jqEj7jqEj7jqEj7jqEj7jqEj7jqE",
      "timestamp": 1704067100,
      "direction": "out",
      "counterparty": "2ojv9BAiHUrvsm9gxDe7fJSzbNZSJcxZvf8dqmWGHG8S",
      "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "symbol": "USDC",
      "amount": 100.0,
      "amountRaw": "100000000",
      "decimals": 6
    }
  ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "5wHu1qwD7Jsj3xqWjdSEJmYr3Q5f5RjXqjqQJ7jqEj7jqEj7jqEj7jqEj7jqEj7jqE"
  }
}

Notes sur les champs

direction : par rapport au portefeuille que vous interrogez. in est pour les jetons reçus (paiement entrant); out est pour les jetons envoyés (paiement sortant).
counterparty : pour les transferts in, l’expéditeur; pour les transferts out, le destinataire.
amount : montant de transfert lisible par l’homme, déjà divisé par decimals. Utilisez cela pour l’affichage (p. ex., 1.5 SOL, 100.0 USDC).
amountRaw : le même montant en tant que chaîne d’entiers bruts, avant ajustement décimal (p. ex., "1500000000" pour 1,5 SOL). Sérialisé en tant que chaîne pour éviter la perte de précision en virgule flottante. Utilisez cela pour les instructions sur la chaîne ou l’arithmétique précise : amount = parseInt(amountRaw) / 10**decimals.
mint : adresse de frappe du jeton (So11111111111111111111111111111111111111111 pour SOL natif).
symbol : symbole du jeton. Tous les jetons n’en ont pas; utilisez l’adresse de frappe lorsque symbol est null.

Cas d’utilisation

Suivre l’historique des paiements d’un commerçant

Surveillez les paiements USDC entrants :

const trackMerchantPayments = async (merchantWallet) => {
  const data = await getWalletTransfers(merchantWallet);

  // Filter for incoming USDC transfers
  const usdcPayments = data.data.filter(t =>
    t.direction === 'in' &&
    t.mint === 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v' // USDC
  );

  console.log(`Received ${usdcPayments.length} USDC payments`);

  const totalReceived = usdcPayments.reduce((sum, t) => sum + t.amount, 0);
  console.log(`Total USDC Received: $${totalReceived.toFixed(2)}`);

  // Display each payment
  usdcPayments.forEach(payment => {
    const date = new Date(payment.timestamp * 1000).toLocaleString();
    console.log(`${date}: $${payment.amount} from ${payment.counterparty}`);
  });

  return {
    count: usdcPayments.length,
    total: totalReceived,
    payments: usdcPayments
  };
};

Générer un reçu de paiement

Créez un reçu détaillé pour un transfert spécifique :

const generatePaymentReceipt = async (address, signature) => {
  const data = await getWalletTransfers(address);

  const transfer = data.data.find(t => t.signature === signature);

  if (!transfer) {
    console.log('Transfer not found');
    return null;
  }

  const receipt = {
    receiptId: transfer.signature.slice(0, 16),
    date: new Date(transfer.timestamp * 1000).toISOString(),
    type: transfer.direction === 'in' ? 'Payment Received' : 'Payment Sent',
    amount: `${transfer.amount} ${transfer.symbol || 'tokens'}`,
    from: transfer.direction === 'in' ? transfer.counterparty : address,
    to: transfer.direction === 'out' ? transfer.counterparty : address,
    transactionUrl: `https://orbmarkets.io/tx/${transfer.signature}`
  };

  console.log('--- PAYMENT RECEIPT ---');
  Object.entries(receipt).forEach(([key, value]) => {
    console.log(`${key}: ${value}`);
  });

  return receipt;
};

Surveiller les motifs de transfert suspects

Détecter une activité de transfert inhabituelle :

const detectSuspiciousActivity = async (address) => {
  const data = await getWalletTransfers(address);

  const recentTransfers = data.data.filter(t => {
    const hourAgo = Date.now() / 1000 - 3600;
    return t.timestamp > hourAgo;
  });

  // Check for high frequency
  if (recentTransfers.length > 100) {
    console.log(`Warning: ${recentTransfers.length} transfers in the last hour`);
  }

  // Check for large amounts
  const largeTransfers = recentTransfers.filter(t => {
    // Assuming USDC/stablecoins
    return t.amount > 10000 && t.decimals === 6;
  });

  if (largeTransfers.length > 0) {
    console.log(`Warning: ${largeTransfers.length} large transfers (>$10k) in the last hour`);
  }

  // Check for transfers to same address
  const counterparties = recentTransfers.map(t => t.counterparty);
  const duplicates = counterparties.filter((item, index) => counterparties.indexOf(item) !== index);

  if (duplicates.length > 5) {
    console.log(`Warning: Multiple transfers to the same address`);
  }

  return {
    recentCount: recentTransfers.length,
    largeTransfers: largeTransfers.length,
    suspiciousPatterns: duplicates.length > 5
  };
};

Construire un flux d’activité de transfert

Créez un flux d’activité convivial :

const buildTransferFeed = async (address) => {
  const data = await getWalletTransfers(address);

  const feed = data.data.map(transfer => {
    const date = new Date(transfer.timestamp * 1000);
    const timeAgo = getTimeAgo(date);

    return {
      id: transfer.signature,
      direction: transfer.direction,
      title: transfer.direction === 'in' ? 'Received' : 'Sent',
      subtitle: `${transfer.amount} ${transfer.symbol || 'tokens'}`,
      description: transfer.direction === 'in'
        ? `from ${transfer.counterparty.slice(0, 8)}...`
        : `to ${transfer.counterparty.slice(0, 8)}...`,
      timeAgo,
      explorerUrl: `https://orbmarkets.io/tx/${transfer.signature}`
    };
  });

  return feed;
};

function getTimeAgo(date) {
  const seconds = Math.floor((new Date() - date) / 1000);

  if (seconds < 60) return 'Just now';
  if (seconds < 3600) return `${Math.floor(seconds / 60)}m ago`;
  if (seconds < 86400) return `${Math.floor(seconds / 3600)}h ago`;
  return `${Math.floor(seconds / 86400)}d ago`;
}

Rapprocher les paiements

Faire correspondre les transferts avec les paiements attendus :

const reconcilePayments = async (address, expectedPayments) => {
  const data = await getWalletTransfers(address);

  const recentTransfers = data.data.filter(t =>
    t.direction === 'in' &&
    t.mint === 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v' // USDC
  );

  const reconciliation = expectedPayments.map(expected => {
    const match = recentTransfers.find(t =>
      Math.abs(t.amount - expected.amount) < 0.01 &&
      t.counterparty === expected.from
    );

    return {
      orderId: expected.orderId,
      expectedAmount: expected.amount,
      status: match ? 'Received' : 'Pending',
      receivedAmount: match?.amount,
      signature: match?.signature,
      timestamp: match?.timestamp
    };
  });

  console.log('Payment Reconciliation:');
  reconciliation.forEach(r => {
    console.log(`Order ${r.orderId}: ${r.status}`);
  });

  return reconciliation;
};

// Example usage
const expected = [
  { orderId: 'ORDER-001', amount: 100.00, from: 'ABC...' },
  { orderId: 'ORDER-002', amount: 250.50, from: 'XYZ...' }
];

reconcilePayments("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY", expected);

Pagination

Pour les portefeuilles avec de nombreux transferts, parcourez les résultats avec le paramètre cursor et pagination.hasMore :

const getAllTransfers = async (address) => {
  let allTransfers = [];
  let cursor = null;

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

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

    allTransfers = allTransfers.concat(data.data);
    cursor = data.pagination.hasMore ? data.pagination.nextCursor : null;

    console.log(`Fetched ${allTransfers.length} transfers so far...`);

  } while (cursor);

  console.log(`\nTotal transfers: ${allTransfers.length}`);
  return allTransfers;
};

Meilleures pratiques

Filtrer côté client pour des jetons spécifiques. L’API retourne tous les transferts de jetons. Filtrez par adresse mint pour suivre des jetons spécifiques comme USDC ou SOL.
Combiner avec l’API d’identité. Utilisez le point de terminaison Identité pour afficher des noms lisibles par l’homme pour des contreparties connues (échanges, protocoles, et autres).
Mettre en cache les transferts récents. Les données de transfert ne changent pas. Mettez en cache les résultats et ne récupérez que les nouveaux transferts depuis votre dernière requête.
Paginer pour un historique complet. Implémentez la pagination pour gérer efficacement les portefeuilles avec des milliers de transferts.
Gérer un symbole manquant. Tous les jetons n’ont pas de champ symbol. Utilisez l’adresse de frappe lorsque symbol est null.

Transferts vs historique des transactions

Fonctionnalité	Transferts	Historique des Transactions
Focus	Uniquement les transferts de jetons	Tous les types de transactions
Données	Infos expéditeur/destinataire	Changements de solde pour tous les jetons
Cas d’utilisation	Suivi des paiements	Journal d’activité complet
Performance	Plus rapide, plus simple	Plus complet

Utilisez Transferts lorsque vous vous souciez uniquement des paiements. Utilisez l’Historique des Transactions lorsque vous avez besoin des données complètes de changement de solde.

Erreurs courantes

Code d’erreur	Description	Solution
400	Format d’adresse de portefeuille invalide	Vérifiez que l’adresse est une adresse Solana valide en base58
401	Clé API manquante ou invalide	Vérifiez que votre clé API est incluse dans la requête
429	Limite de taux dépassée	Réduisez la fréquence des requêtes ou mettez à niveau votre plan

Étapes suivantes

Historique du Portefeuille

Historique complet des transactions avec changements de solde par transaction.

Vue d'ensemble de l'API de Portefeuille

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

Référence de l'API

Schémas de requête et de réponse pour les transferts de jetons.

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 obtenir tous les transferts de portefeuille Solana

Vue d’ensemble

Quand l’utiliser

Démarrage rapide

Requête de base des transferts

Filtrer par direction

Paramètres de requête

Format de réponse

Notes sur les champs

Cas d’utilisation

Suivre l’historique des paiements d’un commerçant

Générer un reçu de paiement

Surveiller les motifs de transfert suspects

Construire un flux d’activité de transfert

Rapprocher les paiements

Meilleures pratiques

Transferts vs historique des transactions

Erreurs courantes

Étapes suivantes

Historique du Portefeuille

Vue d'ensemble de l'API de Portefeuille

Référence de l'API

​Vue d’ensemble

​Quand l’utiliser

​Démarrage rapide

​Requête de base des transferts

​Filtrer par direction

​Paramètres de requête

​Format de réponse

​Notes sur les champs

​Cas d’utilisation

​Suivre l’historique des paiements d’un commerçant

​Générer un reçu de paiement

​Surveiller les motifs de transfert suspects

​Construire un flux d’activité de transfert

​Rapprocher les paiements

​Pagination

​Meilleures pratiques

​Transferts vs historique des transactions

​Erreurs courantes

​Étapes suivantes

Historique du Portefeuille

Vue d'ensemble de l'API de Portefeuille

Référence de l'API

Vue d’ensemble

Quand l’utiliser

Démarrage rapide

Requête de base des transferts

Filtrer par direction

Paramètres de requête

Format de réponse

Notes sur les champs

Cas d’utilisation

Suivre l’historique des paiements d’un commerçant

Générer un reçu de paiement

Surveiller les motifs de transfert suspects

Construire un flux d’activité de transfert

Rapprocher les paiements

Pagination

Meilleures pratiques

Transferts vs historique des transactions

Erreurs courantes

Étapes suivantes