getTransfersByAddress 概要とチュートリアル

概要

getTransfersByAddress は、Helius専用のRPCメソッドで、ウォレットアドレスのために解析された人間が読みやすいトークンとネイティブSOLの転送オブジェクトを返します。これは標準のSolana RPCの一部ではありません。これは転送活動に焦点を当てているため、完全なトランザクションペイロードの代わりに簡潔な転送記録を返します。各記録は、解析されたオーナーとトークンアカウント、ミント、ロー金額、10進数、UI金額、命令位置、確認ステータスで正規化されているため、Solanaトークン解析を再実装せずに残高移動を調整できます。このメソッドは、Developerプランまたはそれ以上のプランが必要で、リクエストごとに10クレジットがかかります。

解析された転送オブジェクト

解析されたアカウント、金額、10進数、転送タイプで人間が読みやすい転送記録を返します。

調整準備完了

SOL、WSOL、Token-2022の手数料、ミント、バーン、アカウントオーナーの変更をモデル化し、残高を正確に調整できます。

ミント、時間、金額のフィルタ

ミントアドレス、ブロックタイム範囲、またはロー金額範囲で転送履歴を絞り込みます。

カウンターパーティフィルタ

withおよびdirectionで送信者または受信者による転送をフィルタリングします。

使用タイミング

次の場合にgetTransfersByAddressを使用してください:

支払いまたは転送の監視のためのウォレット転送履歴
ポートフォリオ活動とトークン移動分析
帳簿および会計のために信頼できる残高調整
カウンターパーティ固有の転送レポート（誰が何を送受信したか）
Solanaトークン解析を書かずにノーマライズされたSOL/WSOL、Token-2022の手数料、ミントおよびバーンの処理

完全なトランザクションデータ、署名のみの履歴、または非転送活動が必要な場合は、代わりにgetTransactionsForAddressを使用してください。一般的なパターンとして、ここで転送をページングしてから、バッチ処理されたgetTransactionを使用して基になる完全なトランザクションをフェッチします（転送行の完全なトランザクションをフェッチを参照）。

精度と調整

getTransfersByAddressは、帳簿、支払い追跡、ポートフォリオ活動、残高調整のために信頼できる転送履歴を必要とするアプリケーション向けに構築されています。生のトランザクションペイロードを返してすべてのエッジケースをパーサに任せる代わりに、APIは正規化された転送オブジェクトを返します。応答は、Solanaの履歴を調整するのが難しい一般的な転送ケースを明示的にモデル化します:

標準的なSPLトークンとネイティブSOLの転送。
保留中の手数料を持つToken-2022の転送は、独立した手数料フィールドを持つ普通のtransfer行として表されます。
ミントとバーンは、null送信者または受信者としての転送として表されます。
SOLの包み込みと解包、その仕組みを表すデフォルトモードで、うるさいライフサイクル行を避けるように設計されています。
SetAuthorityによるトークンアカウントオーナーの変更。
Token-2022の保留中の手数料の引き出し。
推測されたネット移動に圧縮される代わりに基になる転送記録として返される中間アカウントの流れ。

サポートされている可視転送イベントでは、Solanaトークン解析ロジックを再実装せずに残高移動を調整できます。既知の除外、バランス変更からのみ推測される隠されたSOL移動など、制限で指摘されています。

クイックスタート

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

リクエストパラメータ

関連付けられたトークンアカウント（ATA）ではなく、ウォレットオーナーアドレスを渡します。APIは、そのウォレットが所有するトークンアカウントの転送活動を見つけます。

address

string

必須

ベース58のエンコードされたオーナーウォレットアドレス。関連付けられたトークンアカウント（ATA）ではなく、ウォレットオーナーアドレスを渡します。

config

object

フィルタリング、ページング、コミットメント、注文、SOL/WSOLの動作のためのオプションの設定オブジェクト。

with

string

カウンターパーティアドレスでフィルタリングします。このアドレスへのまたはこのアドレスからの転送のみを返します。

direction

string

デフォルト:"any"

addressに対する転送方向でフィルタリングします。

in: addressによって受信された転送
out: addressによって送信された転送
any: 入出転送

mint

string

トークンのミントアドレスでフィルタリングします。ネイティブSOLにはSo11111111111111111111111111111111111111111、WSOLにはSo11111111111111111111111111111111111111112を使用します。

solMode

string

デフォルト:"merged"

ネイティブSOLとWSOLの表現を制御します。

merged: WSOLはネイティブSOLとして扱われます。ラップおよびアンラップのライフサイクル行は除外され、WSOLのミント値はネイティブSOLのミントに書き換えられます。
separate: WSOLは独立したミントとして保持され、ラップおよびアンラップのライフサイクル行が含まれます。

filters

object

金額、ブロック時間、スロットのための追加フィルタ。

limit

number

デフォルト:"100"

返す転送数の最大値。範囲: 1 から 100。

paginationToken

string

ページネーションのための前回の応答からのカーソル。

commitment

string

デフォルト:"finalized"

データのコミットメントレベル。

finalized
confirmed

minContextSlot

number

リクエストが評価できる最小スロット

sortOrder

string

デフォルト:"desc"

結果の順序。

desc: 最新から順
asc: 最古から順

応答

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

応答フィールドの詳細

fromUserAccount と toUserAccount は常に存在します。サイドが存在しない場合、値は null です。
fromTokenAccount と toTokenAccount は、その行にとって意味がある場合にのみ含まれます。ネイティブSOLの転送には完全に省略されています。
ミント転送は片側です: fromUserAccount は null であり、受信者に対するインバウンド転送としてのみ返されます。
バーン転送は片側です: toUserAccount は null であり、バーンオーナーに対するアウトバウンド転送としてのみ返されます。

フィルタ

数値範囲クエリには比較フィルタを使用します。すべての比較フィールドはオプションであり、組み合わせて使用できます。

{
  "gt": 1000000,
  "gte": 1000000,
  "lt": 1000000000,
  "lte": 1000000000
}

フィルタ	タイプ	説明
`amount`	`ComparisonFilter`	生の転送金額、UI金額ではありません。
`blockTime`	`ComparisonFilter`	ブロックのタイムスタンプ（Unix秒）。
`slot`	`ComparisonFilter`	スロット番号。

転送タイプ

typeフィールドは、各行で表される転送動作を識別します。

タイプ	説明	`fromUserAccount`	`toUserAccount`
`transfer`	2つのウォレット間の標準トークンまたはSOL転送。	送信者	受信者
`mint`	ウォレットに新しくミントされたトークン。	`null`	受信者
`burn`	トークンが完全に破棄されました。	送信者	`null`
`wrap`	SOLがWSOLにラップされました。デフォルトでは`solMode: "merged"`に除外されます。	`null`	オーナー
`unwrap`	WSOLがネイティブSOLにアンラップされるか、トークンアカウントを閉じることで賃料が回収されました。デフォルトでは`solMode: "merged"`に除外されます。	オーナー	`null` またはlamportの宛先
`changeOwner`	SetAuthorityによるトークンアカウント所有権の変更。	古いオーナー	新しいオーナー
`withdrawWithheldFee`	ミントまたはアカウントから収集されたToken-2022の保留中の手数料。	`null`	手数料の受取人

転送タイプと命令

転送タイプ	対応する命令	デフォルト表示
`transfer`	`SystemProgram::Transfer`, `SystemProgram::TransferWithSeed`, `SystemProgram::WithdrawNonceAccount`, `SystemProgram::CreateAccount`, `SystemProgram::CreateAccountWithSeed`, `SystemProgram::CreateAccountAllowPrefund`	常に
`transfer`	`Token::Transfer`, `Token::TransferChecked`, `Token-2022::Transfer`, `Token-2022::TransferChecked`	常に
`transfer`	`Token-2022::TransferCheckedWithFee`, `feeAmount`および`feeUiAmount`フィールドを含む	常に
`mint`	`Token::MintTo`, `Token::MintToChecked`	常に
`burn`	`Token::Burn`, `Token::BurnChecked`	常に
`wrap`	`Token::SyncNative`, `Token::InitializeAccount`, `Token::InitializeAccount2`, WSOLライフサイクル処理に使用されるときの`Token::InitializeAccount3`	`solMode: "separate"`のみに表示
`unwrap`	残高がゼロを超えるWSOLでの`Token::CloseAccount`	`solMode: "separate"`のみに表示
`unwrap`	非WSOLトークンアカウントまたはゼロトークン残高のWSOLアカウントのための`Token::CloseAccount`賃料回収	`solMode: "separate"`のみに表示
`changeOwner`	`Token::SetAuthority(AccountOwner)`	常に
`withdrawWithheldFee`	`Token-2022::WithdrawWithheldTokensFromMint`, `Token-2022::WithdrawWithheldTokensFromAccounts`	常に

SOLとwSOLの動作

SOLは、Solana上でユーザーの活動にしばしば一緒に現れる2つの形式で存在します:

ネイティブSOLは、チェーンのネイティブ資産です。これはウォレットまたはアカウントに直接lamportsとして存在します。1 SOLは1,000,000,000 lamportsです。
ラップされたSOL (WSOL, wSOLと書かれることが多い) は、SOLのSPLトークン表現です。これはWSOLミントSo11111111111111111111111111111111111111112を使用し、USDCや他のSPLトークンのようにトークンアカウントに存在します。

ユーザーとアプリケーションは、DeFi、スワップ、トークンアカウントベースの会計、またはSPLトークンのみを受け入れるプログラムインタフェースの場合に、SOLをSPLトークンのように扱う必要がある場合にSOLをラップします。ラッピングは通常、ネイティブSOLで発行されたトークンアカウントを資金提供し、WSOLに同期します。アンラップはWSOLトークンアカウントを閉じ、SOLをlamportの宛先に返します。そのライフサイクルは、「このウォレットと他の人の間でどれくらいのSOLが移動したか」というような単純な質問に答えようとするとややこしい履歴を作成する可能性があります。ラップまたはアンラップは、同じオーナーによって制御されるアカウント間でSOLを移動することがよくあります。これらのライフサイクル行がデフォルトで通常の転送として表示される場合、アプリは活動を二重にカウントしたり、内部会計を外部支払いとして表示したりする可能性があります。デフォルトでは、getTransfersByAddressはsolMode: "merged"を使用します。このモードでは:

ネイティブSOLとWSOLは、So11111111111111111111111111111111111111111によるクエリ時に1つのSOL資産として扱われます。
WSOL転送行はネイティブSOLのミントに正規化され、SOLの名目での履歴が簡単に調整されます。
一般的には、同じオーナーによって制御されるアカウント間の動きを表すため、ラップおよびアンラップのライフサイクル行は除外されます。
異なるオーナー間のSOLおよびWSOLの転送は依然として転送として表されます。
CloseAccountから回収された賃料は、アカウントのクローズライフサイクル行が返される場合、ネイティブSOLのunwrap行として表されます。

独立したSPLトークンミントとしてWSOLが必要な場合や、ラップおよびアンラップのライフサイクルレコードを検査したい場合は、solMode: "separate"を使用します。このモードでは、WSOLはミントSo11111111111111111111111111111111111111112を保持し、ラップアンラップのレコードはtype: "wrap"またはtype: "unwrap"で返されます。 solMode: "separate"でのWSOLアカウントのクローズでは、WSOLミントのunwrapレコードはSOLとして返された残りのWSOLトークン残高を表します。クローズされたトークンアカウントから返された賃料は、別のネイティブSOL unwrap行として返されます。

Token-2022転送料金

Token-2022のTransferCheckedWithFee命令は、type: "transfer"を使用して1つの転送レコードとして表されます。宛先の金額は、amountに返され、保留中の手数料の詳細はfeeAmountとfeeUiAmountに返されます。手数料付きの転送では、送信元はamount + feeAmountで引き落とされ、宛先はamountでクレジットされます。

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

例

USDCでフィルタリング

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "getTransfersByAddress",
  "params": [
    "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY",
    {
      "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
    }
  ]
}

送信者からの着信転送

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "getTransfersByAddress",
  "params": [
    "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY",
    {
      "with": "7hPhaUpydpvm8wtiS3k4LPZKUmivQRs7YQmpE1hFshHx",
      "direction": "in"
    }
  ]
}

金額と時間範囲

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "getTransfersByAddress",
  "params": [
    "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY",
    {
      "mint": "So11111111111111111111111111111111111111112",
      "filters": {
        "amount": {
          "gte": 1000000000,
          "lt": 10000000000
        },
        "blockTime": {
          "gte": 1735718400,
          "lt": 1738396800
        }
      }
    }
  ]
}

ページネーションされたリクエスト

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "getTransfersByAddress",
  "params": [
    "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY",
    {
      "limit": 50,
      "paginationToken": "315069220:308:2:1:splTransfer"
    }
  ]
}

転送行の完全なトランザクションをフェッチ

getTransfersByAddressは、完全なトランザクションペイロードではなく、解析された転送行を返します。各転送の完全なトランザクションが必要な場合は、まず転送をページングし、signatureによって重複を排除し、バッチ処理されたgetTransaction呼び出しで完全なトランザクションをフェッチします。 getTransfersByAddressは複数のオーナーアドレスを跨いでバッチ化できません。1つのオーナーアドレスを一度にクエリしてから、署名によって結果のgetTransactionリクエストをバッチ処理します。単一のトランザクションは複数の転送行を生成する可能性があるため、トランザクションをフェッチする前に常に署名を重複排除してください。

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: 0
        }
      ]
    }));

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

制限

失敗したトランザクションはV1には含まれません。
バランスの変化からのみ推測される隠されたSOLの移動はV1ではサポートされていません。
harvestWithheldTokensToMintは、収集された金額を示さないため、V1ではサポートされていません。
中間アカウントの流れは削減されません。トランザクションが中間アカウントを介して資金を移動する場合、基になる転送記録が返されます。
複数のオーナーアドレスを跨いでのバッチ化はできません。1つのオーナーを一度にクエリします。

次のステップ

getTransactionsForAddress

フィルタリング、並べ替え、トークンアカウントサポートを備えた完全なトランザクション履歴。

APIリファレンス

getTransfersByAddressの完全なリクエストとレスポンススキーマ。

インデックス作成ガイド

移転データを独自のインデックスにバックフィルおよび同期します。

履歴データの概要

すべてのSolana履歴データメソッドを比較します。

はじめに

データストリーミングとイベントリスニング

データ API & RPC

トレーディング

トランザクションの送信

ウォレット・アズ・ア・サービス

ガイド

リソース

getTransfersByAddress 概要とチュートリアル

概要

解析された転送オブジェクト

調整準備完了

ミント、時間、金額のフィルタ

カウンターパーティフィルタ

使用タイミング

精度と調整

クイックスタート

リクエストパラメータ

応答

応答フィールドの詳細

フィルタ

転送タイプ

転送タイプと命令

SOLとwSOLの動作

Token-2022転送料金

例

USDCでフィルタリング

送信者からの着信転送

金額と時間範囲

ページネーションされたリクエスト

転送行の完全なトランザクションをフェッチ

制限

次のステップ

getTransactionsForAddress

APIリファレンス

インデックス作成ガイド

履歴データの概要

​概要

解析された転送オブジェクト

調整準備完了

ミント、時間、金額のフィルタ

カウンターパーティフィルタ

​使用タイミング

​精度と調整

​クイックスタート

​リクエストパラメータ

​応答

​応答フィールドの詳細

​フィルタ

​転送タイプ

​転送タイプと命令

​SOLとwSOLの動作

​Token-2022転送料金

​例

​USDCでフィルタリング

​送信者からの着信転送

​金額と時間範囲

​ページネーションされたリクエスト

​転送行の完全なトランザクションをフェッチ

​制限

​次のステップ

getTransactionsForAddress

APIリファレンス

インデックス作成ガイド

履歴データの概要

概要

使用タイミング

精度と調整

クイックスタート

リクエストパラメータ

応答

応答フィールドの詳細

フィルタ

転送タイプ

転送タイプと命令

SOLとwSOLの動作

Token-2022転送料金

例

USDCでフィルタリング

送信者からの着信転送

金額と時間範囲

ページネーションされたリクエスト

転送行の完全なトランザクションをフェッチ

制限

次のステップ