Cách lấy số dư token trong quá khứ của ví Solana

​

Tổng quan

• Token (SPL / Token-2022): được đọc từ số dư token sau giao dịch, cộng gộp trên các tài khoản token của ví cho mint đó.
• SOL gốc: được đọc từ số dư lamport sau giao dịch. Xác định SOL gốc bằng pseudo-mint So11111111111111111111111111111111111111111.

​

Khi nào nên sử dụng

• Tính PnL: xác định lượng nắm giữ ở đầu và cuối một kỳ.
• Giá vốn và lô thuế: tái dựng số dư tại các sự kiện mua hoặc bán.
• Giải quyết tranh chấp: chứng minh lượng tài sản mà ví nắm giữ tại một thời điểm cụ thể.
• Xác minh ảnh chụp nhanh: kiểm tra số dư ví tại thời điểm chụp nhanh cho airdrop hoặc quản trị.
• Kế toán và kiểm toán: tái dựng trạng thái ví tại ranh giới các kỳ.

​

Bắt đầu nhanh

​

Số dư token tại một dấu thời gian

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"

​

Số dư token tại một thời điểm

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

​

Số dư SOL gốc tại một slot

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

​

Tham số truy vấn

​

Định dạng thời điểm

• Chỉ ngày: 2025-01-10 → nửa đêm UTC
• Ngày + giờ: 2025-01-10 19:20:00 hoặc 2025-01-10T19:20:00 (không bắt buộc có giây) → UTC
• Có múi giờ cụ thể: 2025-01-10T19:20:00Z, 2025-01-10T19:20:00+02:00, 2025-01-10T19:20:00-05:00 → được áp dụng theo giá trị đã cung cấp

​

Định dạng phản hồi

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

​

Ghi chú về các trường

• wallet: lặp lại địa chỉ ví đã truy vấn.
• mint: lặp lại mint đã truy vấn (pseudo-mint SOL khi truy vấn SOL gốc).
• isNative: true khi kết quả là SOL gốc.
• balance: số lượng dễ đọc ở dạng chuỗi thập phân — là chuỗi, không phải số, để số dư lớn không bị mất độ chính xác. Các số 0 ở cuối bị loại bỏ ("1.5", không phải "1.500000").
• balanceRaw: số lượng chính xác theo đơn vị nhỏ nhất (lamport đối với SOL), ở dạng chuỗi.
• decimals: số chữ số thập phân của token (9 đối với SOL).
• requested: lặp lại truy vấn. Khi sử dụng datetime, time cũng được điền bằng số giây epoch đã phân giải, giúp hiển thị rõ cách diễn giải UTC.
• asOf: giao dịch dùng để đọc số dư (slot, blockTime, signature).

​

Trường hợp sử dụng

​

Thay đổi số dư trong một kỳ

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

​

Kiểm tra điều kiện đủ tại thời điểm chụp nhanh

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

​

Phương pháp hay nhất

• Sử dụng slot để nhận kết quả xác định. time và datetime được phân giải thông qua thời gian khối do trình xác thực báo cáo, có thể chênh lệch vài giây. Khi cần khả năng tái lập chính xác (ảnh chụp nhanh, kiểm toán), hãy truy vấn bằng slot.
• Phân tích số dư dưới dạng chuỗi. balance và balanceRaw là chuỗi để duy trì độ chính xác. Hãy sử dụng BigInt(balanceRaw) (hoặc số nguyên có độ chính xác tùy ý của ngôn ngữ bạn dùng) để tính toán — không ép kiểu thành số dấu phẩy động.
• Coi asOf: null là số 0. asOf có giá trị null là một phản hồi thành công, nghĩa là ví không có hoạt động nào với token đó tính đến thời điểm được yêu cầu. Không xử lý trường hợp này như một lỗi.
• Lưu kết quả trong quá khứ vào bộ nhớ đệm. Số dư tại một thời điểm trong quá khứ không bao giờ thay đổi. Hãy lưu kết quả vĩnh viễn vào bộ nhớ đệm để tránh gọi API nhiều lần.

​

Lỗi thường gặp

​

Hạn chế

• Ví có nhiều tài khoản token có thể bị tính thiếu. Số dư được đọc từ một giao dịch khớp gần nhất duy nhất. Trường hợp phổ biến — một tài khoản token liên kết cho mỗi mint — cho kết quả chính xác. Một ví nắm giữ cùng một mint trên nhiều tài khoản token có thể bị tính thiếu nếu giao dịch mới nhất chỉ tác động đến một số tài khoản trong đó.
• Độ chính xác của SOL gốc đối với số dư rất lớn. Đối với số dư SOL vượt quá khoảng 9.007.199 SOL (2⁵³ lamport), độ chính xác có thể bị mất ở thượng nguồn. Số lượng token không bị ảnh hưởng.
• Độ chính xác của time/datetime phụ thuộc vào thời gian khối do trình xác thực báo cáo, có thể chênh lệch vài giây. Hãy sử dụng slot để nhận kết quả chính xác và xác định.
• Mỗi yêu cầu chỉ hỗ trợ một token. Không có dạng xử lý hàng loạt nhiều mint hoặc “tất cả số dư tại thời điểm T”.

​

Bước tiếp theo