Solanaウォレットの過去のトークン残高の取得方法

Wallet APIはベータ版です。エンドポイントおよびレスポンス形式は変更される可能性があります。

概要

Historical Balanceエンドポイントは、過去の特定の時点でウォレットの特定のトークン（またはネイティブSOL）の残高がどうだったのかを答えます。Balances エンドポイントが現在の保有を報告するのに対し、balance-atは任意のタイムスタンプ、日時、またはスロットでの保有を報告します。ウォレットとトークンが関与する要求された時点の直前またはその時点での最新の取引を見つけ、その取引からウォレットの取引後の残高を読み取ります。取引の取引後の残高は、その取引から次の取引までの間に保有した残高です。したがって「時刻Tの残高」は、時刻T以前またはその時点でのブロック時間（またはスロット）での最後の関連取引の取引後の残高です。通常のウォレットでは、これは推定ではなく正確な値です。

トークン (SPL / Token-2022): 取引の取引後トークン残高から読み取り、そのミントに対するウォレットのトークンアカウントで合計します。
ネイティブSOL: 取引のラプトルの取引後残高から読み取ります。ネイティブSOLを擬似ミントとしてアドレス指定します。So11111111111111111111111111111111111111111。

使用するタイミング

Historical Balance APIを使用する場合:

PnL計算: 期間の開始と終了時の保有を決定します。
コストベースと税ロット: 取得または処分イベントでの残高を再構築します。
紛争解決: 特定の瞬間にウォレットが何を保持していたかを証明します。
スナップショットの検証: エアドロップやガバナンススナップショット時のウォレットの残高を確認します。
会計と監査: 期間境界でのウォレット状態を再構築します。

クイックスタート

タイムスタンプでのトークン残高

UnixタイムスタンプでのウォレットのUSDC残高を取得します:

JavaScript
Python
cURL

const getBalanceAt = async (wallet, mint, time) => {
  const url = `https://api.helius.xyz/v1/wallet/${wallet}/balance-at?mint=${mint}&time=${time}&api-key=YOUR_API_KEY`;

  const response = await fetch(url);

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  const result = await response.json();

  if (result.asOf === null) {
    console.log('Wallet had no activity for this token by that time — balance is 0');
    return result;
  }

  console.log(`Balance: ${result.balance}`);
  console.log(`Raw amount: ${result.balanceRaw} (${result.decimals} decimals)`);
  console.log(`As of slot ${result.asOf.slot}, signature ${result.asOf.signature}`);

  return result;
};

// USDC balance on 2025-01-10 19:20:00 UTC
getBalanceAt(
  "5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9",
  "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  1736536800
);

import requests

def get_balance_at(wallet: str, mint: str, time: int):
    url = f"https://api.helius.xyz/v1/wallet/{wallet}/balance-at"
    headers = {"X-Api-Key": "YOUR_API_KEY"}
    params = {"mint": mint, "time": time}

    response = requests.get(url, headers=headers, params=params)
    response.raise_for_status()
    result = response.json()

    if result["asOf"] is None:
        print("Wallet had no activity for this token by that time — balance is 0")
        return result

    print(f"Balance: {result['balance']}")
    print(f"Raw amount: {result['balanceRaw']} ({result['decimals']} decimals)")
    print(f"As of slot {result['asOf']['slot']}, signature {result['asOf']['signature']}")

    return result

# USDC balance on 2025-01-10 19:20:00 UTC
get_balance_at(
    "5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9",
    "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    1736536800
)

curl "https://api.helius.xyz/v1/wallet/5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9/balance-at?mint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&time=1736536800&api-key=YOUR_API_KEY"

日時でのトークン残高

タイムスタンプの代わりに人間が読める日時を渡します。スペースは%20でURLエンコードすることを忘れないでください。

curl "https://api.helius.xyz/v1/wallet/5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9/balance-at?mint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&datetime=2025-01-10%2019:20:00&api-key=YOUR_API_KEY"

スロットでのネイティブSOL残高

ネイティブSOLの場合は、擬似ミントSo11111111111111111111111111111111111111111を使用します。スロットに基づいたクエリは正確で決定的です。

curl "https://api.helius.xyz/v1/wallet/5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9/balance-at?mint=So11111111111111111111111111111111111111111&slot=313000000&api-key=YOUR_API_KEY"

クエリパラメータ

パラメータ	必須	タイプ	説明
`mint`	はい	string	トークンミントアドレス。ネイティブSOLの場合は`So11111111111111111111111111111111111111111`を使用します。
`time`	いずれか一つ	int	Unixタイムスタンプ（秒）。この時点での残高。
`datetime`	いずれか一つ	string	日時文字列。例: `2025-01-10 19:20:00`。デフォルトではUTCです。
`slot`	いずれか一つ	int	スロット番号。このスロットでの残高。正確で決定的です。

time, datetime, slotのいずれか一つを提供する必要があります。0または複数を提供すると、400エラーが返されます。

日時形式

受け入れ可能な形式:

日付のみ: 2025-01-10 → UTCの真夜中
日付 + 時刻: 2025-01-10 19:20:00 または 2025-01-10T19:20:00（秒はオプション） → UTC
明示的なタイムゾーン: 2025-01-10T19:20:00Z, 2025-01-10T19:20:00+02:00, 2025-01-10T19:20:00-05:00 → 指定通りに処理

無効またはサポートされていない形式（01/10/2025, 2025-13-10, 2025-02-30）は400エラーを返します。

日時はデフォルトではUTCとして解釈されます。2025-01-10 19:20:00のような単純な日時は、あなたの現地時間ではなくUTCとして扱われます。別の意図がある場合は明示的なタイムゾーンオフセットを含めてください。レスポンスのrequested.timeフィールドは、解釈を確認できるように解決されたエポック秒を示します。

レスポンス形式

{
  "wallet": "5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9",
  "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "isNative": false,
  "balance": "284961463.392936",
  "balanceRaw": "284961463392936",
  "decimals": 6,
  "requested": {
    "time": 1736536800,
    "slot": null,
    "datetime": null
  },
  "asOf": {
    "slot": 313000000,
    "blockTime": 1736536794,
    "signature": "5Cyy7Mh9nVgFq3T8wJp2sKxR4dE6bA1uZoNcLrXmYqUpon"
  }
}

フィールドノート

wallet: 照会されたウォレットアドレスのエコー。
mint: 照会されたミントのエコー（ネイティブの場合はSOLの擬似ミント）。
isNative: 結果がネイティブSOLの場合はtrue。
balance: 10進文字列としての人間が読める量 — 文字列であり数値ではないため、大きな残高でも精度を失いません。末尾のゼロはトリムされます（"1.5"ではなく"1.500000"）。
balanceRaw: 最小単位での正確な量（SOLの場合はラプトル）として、文字列。
decimals: トークンの小数点以下の桁数（SOLでは9）。
requested: クエリのエコー。datetimeが使用された場合、timeも解決されたエポック秒で設定され、UTCの解釈が表示されます。
asOf: 残高が読み取られた取引（slot, blockTime, signature）。

asOf: nullはエラーではなくゼロを意味します。要求された時点でウォレットに一致する取引がない場合、エンドポイントは200を返し、balance: "0"とasOf: null — ウォレットはその時点までにトークンを保持していなかったことを示します。

使用ケース

期間中の残高変動

2つの時点での保有を比較します。

const getBalanceChange = async (wallet, mint, startTime, endTime) => {
  const fetchBalance = (time) =>
    fetch(
      `https://api.helius.xyz/v1/wallet/${wallet}/balance-at?mint=${mint}&time=${time}&api-key=YOUR_API_KEY`
    ).then(r => r.json());

  const [start, end] = await Promise.all([
    fetchBalance(startTime),
    fetchBalance(endTime)
  ]);

  // balanceRaw is an exact integer string — use BigInt for precise arithmetic
  const delta = BigInt(end.balanceRaw) - BigInt(start.balanceRaw);
  const human = Number(delta) / 10 ** end.decimals;

  console.log(`Start: ${start.balance}`);
  console.log(`End: ${end.balance}`);
  console.log(`Change: ${human > 0 ? '+' : ''}${human}`);

  return { start, end, delta };
};

スナップショットの適格性確認

ウォレットがスナップショットスロットでトークンを保持していたかを確認します。

const heldAtSnapshot = async (wallet, mint, snapshotSlot, minimumRaw) => {
  const result = await fetch(
    `https://api.helius.xyz/v1/wallet/${wallet}/balance-at?mint=${mint}&slot=${snapshotSlot}&api-key=YOUR_API_KEY`
  ).then(r => r.json());

  const eligible = BigInt(result.balanceRaw) >= BigInt(minimumRaw);
  console.log(`${wallet}: ${result.balance} at slot ${snapshotSlot} — ${eligible ? 'eligible' : 'not eligible'}`);

  return eligible;
};

ベストプラクティス

決定的な結果にはslotを使用します。 timeとdatetimeはバリデーター報告のブロック時間を通じて解決され、数秒のドリフトが発生する可能性があります。正確さが重要な場合（スナップショット、監査）、slotでクエリします。
残高を文字列として解析します。 balanceとbalanceRawは精度を維持するために文字列です。計算にはBigInt(balanceRaw)（またはあなたの言語の任意精度整数）を使用します - 浮動小数点数にキャストしないでください。
asOf: nullをゼロと見なします。 null asOfは、要求された時点でそのトークンに対するウォレットの活動がなかったことを意味する成功した応答です。エラーとして扱わないでください。
過去の結果をキャッシュします。 過去の時点での残高は変わりません。繰り返しのAPI呼び出しを避けるために結果を永久にキャッシュします。

共通のエラー

エラーコード	説明	解決策
400	`mint` が欠落している、有効でないミント、`time`, `datetime`, `slot` の0個または複数、または解釈できない`datetime`	有効なミントと正確に1つの時点パラメータを提供します
401	APIキーが欠落しているか無効	リクエストにAPIキーが含まれていることを確認します
404	パス内の無効なウォレットアドレス	アドレスが有効なbase58 Solanaアドレスであることを確認します
429	レート制限を超過	リクエスト頻度を下げるか、プランをアップグレードします
502	上流のRPCエラーまたはタイムアウト	指数バックオフを使用して再試行します

制限事項

マルチトークンアカウントウォレットは過少カウントされる可能性があります。 残高は最新の一致する取引から読み取られます。一般的なケース（ミントごとに1つの関連トークンアカウント）は正確です。複数のトークンアカウントに同じミントを保持しているウォレットでは、最新の取引がそれらの一部にしか触れていない場合、過少カウントされる可能性があります。
非常に大きな残高のネイティブSOLの精度。 約9,007,199 SOL（2⁵³ラプトル）を超えるSOL残高は、上流で精度が失われる可能性があります。トークン量は影響されません。
time/datetimeの精度はバリデーター報告のブロック時間に依存しますが、数秒ドリフトする可能性があります。正確で決定的な結果にはslotを使用します。
リクエストあたり1つのトークンのみ。 複数のミントや「時刻Tでのすべての残高」のバッチ形式はありません。

次のステップ

ウォレットの残高

USD値を含むウォレットの現在のトークンおよびNFT保有を取得。

ウォレットAPIの概要

すべてのウォレットAPIエンドポイントおよび共通規約。

APIリファレンス

履歴のある残高のリクエストおよびレスポンススキーマ。

はじめに

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

データ API & RPC

トレーディング

トランザクションの送信

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

ガイド

リソース

Solanaウォレットの過去のトークン残高の取得方法

概要

使用するタイミング

クイックスタート

タイムスタンプでのトークン残高

日時でのトークン残高

スロットでのネイティブSOL残高

クエリパラメータ

日時形式

レスポンス形式

フィールドノート

使用ケース

期間中の残高変動

スナップショットの適格性確認

ベストプラクティス

共通のエラー

制限事項

次のステップ

ウォレットの残高

ウォレットAPIの概要

APIリファレンス

​概要

​使用するタイミング

​クイックスタート

​タイムスタンプでのトークン残高

​日時でのトークン残高

​スロットでのネイティブSOL残高

​クエリパラメータ

​日時形式

​レスポンス形式

​フィールドノート

​使用ケース

​期間中の残高変動

​スナップショットの適格性確認

​ベストプラクティス

​共通のエラー

​制限事項

​次のステップ

ウォレットの残高

ウォレットAPIの概要

APIリファレンス

概要

使用するタイミング

クイックスタート

タイムスタンプでのトークン残高

日時でのトークン残高

スロットでのネイティブSOL残高

クエリパラメータ

日時形式

レスポンス形式

フィールドノート

使用ケース

期間中の残高変動

スナップショットの適格性確認

ベストプラクティス

共通のエラー

制限事項

次のステップ