> ## 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. # Présentation et Tutoriel de getTransfersByAddress > Interrogez des objets de transfert de token et de SOL natif analysés et lisibles pour une adresse Solana avec des filtres par mint, temps, montant et contrepartie. ## Présentation [`getTransfersByAddress`](/docs/fr/api-reference/rpc/http/gettransfersbyaddress) est une méthode RPC exclusive à Helius qui renvoie des objets de transfert de token et de SOL natif analysés et lisibles pour une adresse de portefeuille. Ce n'est pas une partie du RPC standard de Solana. Elle est axée sur l'activité de transfert, donc elle renvoie des enregistrements de transfert concis au lieu de charges utiles de transaction complètes. Chaque enregistrement est normalisé avec des comptes propriétaires et de token analysés, des mints, des montants bruts, des décimales, des montants UI, des positions d'instruction et un statut de confirmation, afin que vous puissiez réconcilier le mouvement de solde sans réimplémenter l'analyse des tokens Solana. Cette méthode nécessite un [plan Développeur](/docs/fr/billing/plans) ou supérieur et coûte 10 crédits par demande. Retournent des enregistrements de transfert lisibles humainement avec des comptes, montants, décimales, et types de transfert analysés. Modélisez les frais SOL, WSOL, Token-2022, les mints, burning, et changements de propriétaires de compte pour que les soldes puissent être réconciliés précisément. Réduisez l'historique de transfert par adresse de mint, plage de temps de bloc ou plage de montants bruts. Filtrez les transferts par expéditeur ou destinataire avec `with` et `direction`. ## Quand l'utiliser Utilisez `getTransfersByAddress` quand vous avez besoin de : * Historique de transfert de portefeuille pour les paiements ou la surveillance des transferts * Analyse de l'activité de portefeuille et du mouvement des tokens * Réconciliation de solde fiable pour les registres comptables * Rapports de transfert spécifiques par contrepartie (qui a envoyé ou reçu quoi) * Gestion normalisée du SOL/WSOL, frais Token-2022, mint, et burning sans écrire d'analyseur Utilisez [`getTransactionsForAddress`](/docs/fr/rpc/gettransactionsforaddress) à la place quand vous avez besoin de données de transaction complètes, d'un historique des signatures uniquement, ou d'activités non liées aux transferts. Un modèle courant est de parcourir les transferts ici, puis de récupérer les transactions complètes sous-jacentes avec des appels groupés [`getTransaction`](/docs/fr/api-reference/rpc/http/gettransaction) (voir [Récupérer les transactions complètes pour les lignes de transfert](#récupérer-les-transactions-complètes-pour-les-lignes-de-transfert)). ## Précision et réconciliation `getTransfersByAddress` est conçu pour les applications qui ont besoin d'un historique de transfert fiable pour les registres, le suivi des paiements, l'activité des portefeuilles et la réconciliation des soldes. Plutôt que de retourner des charges utiles de transaction brutes et de laisser chaque cas limite à votre analyseur, l'API retourne des objets de transfert normalisés. La réponse modélise explicitement les cas de transfert qui rendent souvent l'historique de Solana difficile à réconcilier : * Transferts de SOL natif et de token SPL standard. * Transferts Token-2022 avec frais retenus, représentés comme des lignes `transfer` ordinaires avec des champs de frais séparés. * Mints et burnings, représentés comme des transferts avec un expéditeur ou destinataire `null`. * Comportement de wrapping et unwrapping du SOL, avec un mode par défaut conçu pour éviter les lignes de cycle de vie bruyantes. * Changements de propriétaires de compte de token via SetAuthority. * Retraits de frais retenus de Token-2022. * Flux de comptes intermédiaires, retournés comme les enregistrements de transfert sous-jacents plutôt que d'être regroupés en un mouvement net deviné. Pour les événements de transfert visibles pris en charge, cela vous permet de réconcilier le mouvement des soldes sans réimplémenter la logique d'analyse de token Solana. Les exclusions connues, telles que les mouvements de SOL cachés déduits uniquement des changements de solde, sont signalées dans [Limitations](#limitations). ## Démarrage rapide ```javascript theme={"system"} const response = await fetch("https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ jsonrpc: "2.0", id: "1", method: "getTransfersByAddress", params: ["86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY"] }) }); const data = await response.json(); console.log(data.result.data); ``` ## Paramètres de requête Passez l'adresse propriétaire du portefeuille, pas un compte de token associé (ATA). L'API trouve l'activité de transfert pour les comptes de token détenus par ce portefeuille. Adresse de portefeuille propriétaire encodée en Base58 pour interroger les transferts. Passez l'adresse propriétaire du portefeuille, pas un compte de token associé (ATA). Objet de configuration optionnel pour le filtrage, la pagination, l'engagement, le tri, et le comportement SOL/WSOL. Filtrer par adresse de contrepartie. Ne renvoie que les transferts vers ou depuis cette adresse. Filtrer par direction de transfert par rapport à `address`. * `in` : transferts reçus par `address` * `out` : transferts envoyés par `address` * `any` : transferts entrants et sortants Filtrer par adresse de mint de token. Utilisez `So11111111111111111111111111111111111111111` pour SOL natif et `So11111111111111111111111111111111111111112` pour WSOL. Contrôle comment le SOL natif et le WSOL sont représentés. * `merged` : le WSOL est traité comme SOL natif. Les lignes de cycle de vie de wrapping et unwrapping sont exclues, et les valeurs de mint WSOL sont réécrites au mint de SOL natif. * `separate` : le WSOL est préservé comme un mint distinct, et les lignes de cycle de vie de wrapping et unwrapping sont incluses. Filtres supplémentaires pour le montant, le temps de bloc, et le slot. Nombre maximal de transferts à retourner. Plage : 1 à 100. Curseur de la réponse précédente pour la pagination. Niveau d'engagement des données. * `finalized` * `confirmed` Le slot minimal auquel la demande peut être évaluée Ordre des résultats. * `desc` : le plus récent en premier * `asc` : le plus ancien en premier ## Réponse ```json theme={"system"} { "jsonrpc": "2.0", "id": "1", "result": { "data": [ { "signature": "5GEX7Q3X5Q8yJGbKYoR7mtzQmG8tpoEwzjPgqVmn3y5xg3yKwqXcDdN5YVcc9V6vA4TuH5iM6FHRVhTxvz4AX2zG", "slot": 315073428, "blockTime": 1736159420, "type": "transfer", "fromUserAccount": "7hPhaUpydpvm8wtiS3k4LPZKUmivQRs7YQmpE1hFshHx", "toUserAccount": "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY", "fromTokenAccount": "HcvK3EJ74iM9g11cUgsaPvLSrhCvCwcrWxBNd87LsC1x", "toTokenAccount": "CBcYniR9G9CN3zGMnwNE4SWbqkYWvCFVreEob9xHnQCY", "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "amount": "2500000", "decimals": 6, "uiAmount": "2.5", "confirmationStatus": "finalized", "transactionIdx": 35, "instructionIdx": 1, "innerInstructionIdx": 0 } ], "paginationToken": "315073428:35:1:0:splTransfer" } } ``` ### Détails du champ de réponse * `fromUserAccount` et `toUserAccount` sont toujours présents. Lorsqu'un côté n'existe pas, la valeur est `null`. * `fromTokenAccount` et `toTokenAccount` sont inclus uniquement lorsque les points de terminaison des comptes de token sont significatifs pour la ligne. Ils sont complètement omis pour les transferts de SOL natif. * Les transferts de mint sont unilatéraux : `fromUserAccount` est `null`, et ils ne peuvent être retournés que comme transferts entrants pour le destinataire. * Les transferts de burning sont unilatéraux : `toUserAccount` est `null`, et ils ne peuvent être retournés que comme transferts sortants pour le propriétaire brûlant. ## Filtres Utilisez des filtres de comparaison pour les requêtes de plage numérique. Tous les champs de comparaison sont optionnels et peuvent être combinés. ```json theme={"system"} { "gt": 1000000, "gte": 1000000, "lt": 1000000000, "lte": 1000000000 } ``` | Filtre | Type | Description | | ----------- | ------------------ | --------------------------------------------- | | `amount` | `ComparisonFilter` | Montant brut de transfert, pas le montant UI. | | `blockTime` | `ComparisonFilter` | Timestamp de bloc en secondes Unix. | | `slot` | `ComparisonFilter` | Numéro de slot. | ## Types de transferts Le champ `type` identifie le comportement de transfert représenté par chaque ligne. | Type | Description | `fromUserAccount` | `toUserAccount` | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------- | ----------------------------- | | `transfer` | Transfert de token ou SOL standard entre deux portefeuilles. | Expéditeur | Destinataire | | `mint` | Nouveaux tokens mintés à un portefeuille. | `null` | Destinataire | | `burn` | Tokens détruits de façon permanente. | Expéditeur | `null` | | `wrap` | SOL wrappé en WSOL. Exclu par défaut dans `solMode: "merged"`. | `null` | Propriétaire | | `unwrap` | WSOL déwrappé en SOL natif, ou loyer récupéré de la fermeture d'un compte de token. Exclu par défaut dans `solMode: "merged"`. | Propriétaire | `null` ou destination lamport | | `changeOwner` | Changement de propriétaire de compte de token via SetAuthority. | Ancien propriétaire | Nouveau propriétaire | | `withdrawWithheldFee` | Frais retenus de Token-2022 collectés d'un mint ou de comptes. | `null` | Destinataire des frais | ### Types de transferts et instructions | Type de transfert | Instructions couvertes | Visibilité par défaut | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | | `transfer` | `SystemProgram::Transfer`, `SystemProgram::TransferWithSeed`, `SystemProgram::WithdrawNonceAccount`, `SystemProgram::CreateAccount`, `SystemProgram::CreateAccountWithSeed`, `SystemProgram::CreateAccountAllowPrefund` | Toujours | | `transfer` | `Token::Transfer`, `Token::TransferChecked`, `Token-2022::Transfer`, `Token-2022::TransferChecked` | Toujours | | `transfer` | `Token-2022::TransferCheckedWithFee`, avec `feeAmount` et `feeUiAmount` fields | Toujours | | `mint` | `Token::MintTo`, `Token::MintToChecked` | Toujours | | `burn` | `Token::Burn`, `Token::BurnChecked` | Toujours | | `wrap` | `Token::SyncNative`, `Token::InitializeAccount`, `Token::InitializeAccount2`, `Token::InitializeAccount3` lorsque utilisé pour la gestion du cycle de vie WSOL | `solMode: "separate"` seulement | | `unwrap` | `Token::CloseAccount` sur WSOL avec solde supérieur à zéro | `solMode: "separate"` seulement | | `unwrap` | `Token::CloseAccount` récupération de loyer pour les comptes de tokens non-WSOL, ou comptes WSOL avec solde de token zéro | `solMode: "separate"` seulement | | `changeOwner` | `Token::SetAuthority(AccountOwner)` | Toujours | | `withdrawWithheldFee` | `Token-2022::WithdrawWithheldTokensFromMint`, `Token-2022::WithdrawWithheldTokensFromAccounts` | Toujours | ## Comportement SOL et wSOL Le SOL existe sur Solana sous deux formes qui apparaissent souvent ensemble dans l'activité réelle des utilisateurs : * **SOL natif** est l'actif natif de la chaîne. Il vit directement dans un portefeuille ou un compte sous forme de lamports. Un SOL équivaut à 1 000 000 000 de lamports. * **Wrapped SOL (WSOL, souvent écrit wSOL)** est une représentation de token SPL du SOL. Il utilise le mint WSOL `So11111111111111111111111111111111111111112` et réside dans un compte de token, comme USDC ou tout autre token SPL. Les utilisateurs et applications wrappent le SOL lorsqu'ils ont besoin que le SOL se comporte comme un token SPL, généralement pour DeFi, les swaps, la comptabilité basée sur des comptes de tokens, ou les interfaces de programme acceptant uniquement les tokens SPL. Le wrapping alimente généralement un compte de token avec du SOL natif et le synchronise en WSOL. L'unwrapping ferme le compte de token WSOL et retourne le SOL à une destination en lamports. Ce cycle de vie peut créer un historique déroutant si vous essayez de répondre à une question simple comme "combien de SOL a été transféré entre ce portefeuille et quelqu'un d'autre ?" Un wrap ou unwrap déplace souvent le SOL entre des comptes contrôlés par le même propriétaire. Si ces lignes de cycle de vie sont montrées comme des transferts ordinaires par défaut, les applications peuvent comptabiliser deux fois l'activité ou montrer une comptabilité interne comme des paiements externes. Par défaut, `getTransfersByAddress` utilise `solMode: "merged"`. Dans ce mode : * Le SOL natif et le WSOL sont traités comme un seul actif SOL lors de la requête par `So11111111111111111111111111111111111111111`. * Les lignes de transfert WSOL sont normalisées au mint de SOL natif pour faciliter la réconciliation de l'historique en SOL. * Les lignes de cycle de vie de wrapping et unwrapping sont exclues car elles représentent généralement un mouvement entre des comptes contrôlés par le même propriétaire, pas un paiement à un autre utilisateur. * Les transferts de SOL et WSOL entre différents propriétaires sont toujours représentés comme des transferts. * Le loyer récupéré par `CloseAccount` est représenté comme une ligne `unwrap` de SOL natif lorsque les lignes de cycle de vie de clôture de compte sont retournées. Utilisez `solMode: "separate"` lorsque vous avez besoin que le WSOL soit un mint distinct de token SPL ou que vous souhaitez inspecter les enregistrements de cycle de vie de wrapping et unwrapping. Dans ce mode, le WSOL conserve le mint `So11111111111111111111111111111111111111112`, et les enregistrements de wrapping/unwrapping sont retournés avec `type: "wrap"` ou `type: "unwrap"`. Pour les fermetures de comptes WSOL dans `solMode: "separate"`, les enregistrements `unwrap` pour le mint WSOL représentent le solde de token WSOL restant retourné comme SOL. Le loyer remboursé du compte de token fermé est retourné comme une ligne `unwrap` de SOL natif séparée. ## Frais de transfert Token-2022 Les instructions `TransferCheckedWithFee` de Token-2022 sont représentées comme un enregistrement de transfert avec `type: "transfer"`. Le montant de destination est retourné dans `amount` ; les détails des frais retenus sont retournés dans `feeAmount` et `feeUiAmount`. Pour les transferts avec frais, la source est débitée `amount + feeAmount`, tandis que la destination est créditée `amount`. ```json theme={"system"} { "signature": "WcvF2eFxArpqRJySzDuiP6Xw8BMprWytMpYCxk2ExBt5C1WyxWzDWcCWXW8iKQVYR9AtdQxPE1uu1SMEZvbbhdr", "slot": 409259683, "blockTime": 1774635210, "type": "transfer", "fromUserAccount": "5aZZ4duJUKiMsJN9vRsoAn4SDX7agvKu7Q3QdFWRfWze", "toUserAccount": "FESSvM1cVUchc13XQY8e41oeYxMnyqQNYVZwoznfJsTo", "fromTokenAccount": "3VUYGjYktCzNhDVymNb3Z1iHewtfPFRvdA53qSWuxdXy", "toTokenAccount": "51cEFBA1virMuPqHXvNGs8FKKTMqeEVKzugv1hqPU2Zc", "mint": "CKfatsPMUf8SkiURsDXs7eK6GWb4Jsd6UDbs7twMCWxo", "amount": "48650000", "decimals": 5, "uiAmount": "486.5", "feeAmount": "13450000", "feeUiAmount": "134.5", "confirmationStatus": "finalized", "transactionIdx": 1315, "instructionIdx": 4, "innerInstructionIdx": 0 } ``` ## Exemples ### Filtrer par USDC ```json theme={"system"} { "jsonrpc": "2.0", "id": "1", "method": "getTransfersByAddress", "params": [ "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY", { "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" } ] } ``` ### Transferts entrants d'un expéditeur ```json theme={"system"} { "jsonrpc": "2.0", "id": "1", "method": "getTransfersByAddress", "params": [ "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY", { "with": "7hPhaUpydpvm8wtiS3k4LPZKUmivQRs7YQmpE1hFshHx", "direction": "in" } ] } ``` ### Plage de montant et de temps ```json theme={"system"} { "jsonrpc": "2.0", "id": "1", "method": "getTransfersByAddress", "params": [ "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY", { "mint": "So11111111111111111111111111111111111111112", "filters": { "amount": { "gte": 1000000000, "lt": 10000000000 }, "blockTime": { "gte": 1735718400, "lt": 1738396800 } } } ] } ``` ### Requête paginée ```json theme={"system"} { "jsonrpc": "2.0", "id": "1", "method": "getTransfersByAddress", "params": [ "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY", { "limit": 50, "paginationToken": "315069220:308:2:1:splTransfer" } ] } ``` ### Récupérer les transactions complètes pour les lignes de transfert `getTransfersByAddress` retourne des lignes de transfert analysées, pas des charges utiles de transaction complètes. Si vous avez besoin de la transaction complète pour chaque transfert, parcourez d'abord les transferts, dédupliquez par `signature`, puis récupérez les transactions complètes avec des appels groupés [`getTransaction`](/docs/fr/api-reference/rpc/http/gettransaction). `getTransfersByAddress` n'est pas batchable pour plusieurs adresses propriétaires. Interrogez une adresse propriétaire à la fois, puis regroupez les demandes `getTransaction` résultantes par signature. Une seule transaction peut émettre plusieurs lignes de transfert, donc dédupliquez toujours les signatures avant de récupérer les transactions. ```javascript theme={"system"} const API_KEY = "YOUR_API_KEY"; const RPC_URL = `https://mainnet.helius-rpc.com/?api-key=${API_KEY}`; const OWNER_ADDRESS = "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY"; async function rpc(method, params) { const response = await fetch(RPC_URL, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ jsonrpc: "2.0", id: "1", method, params }) }); const body = await response.json(); if (body.error) { throw new Error(body.error.message); } return body.result; } async function getAllTransfers(address) { const transfers = []; let paginationToken; do { const result = await rpc("getTransfersByAddress", [ address, { limit: 100, ...(paginationToken ? { paginationToken } : {}) } ]); transfers.push(...result.data); paginationToken = result.paginationToken; } while (paginationToken); return transfers; } async function getTransactionsInBatches(signatures, batchSize = 100) { const transactions = []; for (let i = 0; i < signatures.length; i += batchSize) { const batch = signatures.slice(i, i + batchSize).map((signature, index) => ({ jsonrpc: "2.0", id: `${i + index}`, method: "getTransaction", params: [ signature, { encoding: "jsonParsed", maxSupportedTransactionVersion: 1 } ] })); const response = await fetch(RPC_URL, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(batch) }); const results = await response.json(); for (const item of results) { if (item.error) { throw new Error(item.error.message); } transactions.push(item.result); } } return transactions; } const transfers = await getAllTransfers(OWNER_ADDRESS); const signatures = [...new Set(transfers.map((transfer) => transfer.signature))]; const transactions = await getTransactionsInBatches(signatures); console.log(`Fetched ${transfers.length} transfer rows`); console.log(`Fetched ${transactions.length} unique transactions`); ``` ## Limitations * Les transactions échouées ne sont pas incluses dans la V1. * Les mouvements de SOL cachés déduits uniquement des changements de solde ne sont pas pris en charge dans la V1. * `harvestWithheldTokensToMint` n'est pas pris en charge dans la V1 car il n'indique pas le montant collecté. * Les flux de comptes intermédiaires ne sont pas réduits. Si une transaction déplace des fonds via des comptes intermédiaires, les enregistrements de transfert sous-jacents sont retournés. * Non batchable pour plusieurs adresses propriétaires. Interrogez un propriétaire à la fois. ## Étapes suivantes Historique des transactions complètes avec filtrage, tri, et support des comptes de token. Schéma complet de la demande et de la réponse pour getTransfersByAddress. Remplissez et synchronisez les données de transfert dans votre propre index. Comparez toutes les méthodes de données historiques de Solana.