Solana 지갑의 과거 토큰 잔액 가져오는 방법

지갑 API는 베타 버전입니다. 엔드포인트와 응답 형식은 변경될 수 있습니다.

개요

과거 잔액 엔드포인트는 질문에 답합니다: 과거 특정 시점에 이 지갑의 특정 토큰 (또는 네이티브 SOL) 잔액은 얼마였습니까? Balances 엔드포인트가 현재 보유량을 보고하는 동안, balance-at는 어느 타임스탬프, 날짜 및 시간 또는 슬롯에서든 보유량을 보고합니다. 이 엔드포인트는 지갑 및 토큰과 관련된 요청한 시점 직전 또는 해당 시점의 가장 최근 거래를 찾아 해당 거래의 거래 후 잔액을 읽습니다. 거래의 거래 후 잔액은 그 거래부터 다음 거래까지 유지된 잔액이므로, “시점 T에서의 잔액”은 T 시점 직전 또는 동일한 블록 시간 (또는 슬롯)에서 마지막 관련 거래의 거래 후 잔액입니다. 일반적인 지갑의 경우, 이는 추정치가 아닌 정확한 값입니다.

토큰 (SPL / Token-2022): 거래의 포스트 토큰 잔액에서 읽으며, 지갑의 토큰 계좌가 가지고 있는 그것들을 합산합니다.
네이티브 SOL: 거래의 램포트 포스트 잔액에서 읽습니다. 네이티브 SOL은 가상 민트 So11111111111111111111111111111111111111111로 주소를 지정합니다.

사용 시기

다음 상황에서 과거 잔액 API를 사용하세요:

PnL 계산: 기간 시작과 종료 시 보유량 확인.
비용 기준 및 세금 항목: 취득 또는 처분 이벤트 시 잔액 재구성.
분쟁 해결: 특정 순간에 지갑이 무엇을 보유했는지 증명.
스냅샷 확인: 에어드롭 또는 거버넌스 스냅샷에서 지갑의 잔액 확인.
회계 및 감사: 기간 경계에서 지갑 상태 재구성.

시작하기

타임스탬프에서의 토큰 잔액

유닉스 타임스탬프에서 지갑의 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	초 단위의 유닉스 타임스탬프. 이 시간의 잔액.
`datetime`	하나 선택	string	날짜 및 시간 문자열, 예: `2025-01-10 19:20:00`. 기본적으로 UTC.
`slot`	하나 선택	int	슬롯 번호. 이 슬롯의 잔액. 정확하고 결정적입니다.

time, datetime 또는 slot 중 정확히 하나를 제공해야 합니다. 0개 또는 1개 이상을 제공하면 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: 소수 문자열로서의 사람이 읽을 수 있는 금액 — 대용량 잔액이 정밀도를 잃지 않도록 문자열로 표시됩니다. 후행 0은 잘려 나갑니다 ("1.5", "1.500000" 아님).
balanceRaw: 작은 단위로의 정확한 금액 (SOL의 경우 램포트)으로, 문자열로 표시됩니다.
decimals: 토큰 소수 (SOL의 경우 9).
requested: 쿼리의 에코. datetime이 사용될 때 time도 해석된 시대 초로 채워져 UTC 해석이 보입니다.
asOf: 잔액이 읽힌 거래 (slot, blockTime, signature).

asOf: null는 0을 의미하며, 오류가 아닙니다. 요청한 시점에 지갑에 일치하는 거래가 없었던 경우, 엔드포인트는 200와 balance: "0" 및 asOf: null를 반환합니다 — 지갑은 그때까지 토큰을 보유한 적이 없었던 것입니다.

사용 사례

기간 동안의 잔액 변화

두 시점 간의 보유량 비교:

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) (또는 언어의 임의 정밀도 정수)를 산술에 사용하세요 — float로 형변환하지 마세요.
asOf: null를 0으로 처리하세요. null asOf는 요청된 시점까지 지갑에 해당 토큰에 대한 활동이 없었음을 의미하는 성공적인 응답입니다. 오류로 처리하지 마십시오.
과거 결과를 캐시하세요. 과거의 시점에서의 잔액은 절대로 변하지 않습니다. 반복적인 API 호출을 피하기 위해 결과를 영구적으로 캐시하세요.

일반 오류

오류 코드	설명	해결책
400	`mint` 누락, 잘못된 민트, `time`/`datetime`/`slot`의 0개 또는 여러개, 또는 파싱할 수 없는 `datetime`	유효한 민트와 정확히 하나의 시점 매개변수를 제공하십시오
401	API 키 누락 또는 잘못됨	요청에 API 키가 포함되어 있는지 확인하세요
404	경로에 잘못된 지갑 주소	주소가 유효한 base58 Solana 주소인지 확인하세요
429	비율 제한 초과	요청 빈도를 줄이거나 플랜을 업그레이드하세요
502	업스트림 RPC 오류 또는 시간 초과	지수적 백오프로 재시도하세요

한계

다중 토큰 계좌 지갑은 과소 계산될 수 있습니다. 잔액은 일치하는 단일 가장 최근 거래로부터 읽습니다. 민트당 하나의 관련 토큰 계좌를 가진 일반적인 경우에는 정확합니다. 여러 토큰 계좌에 걸쳐 동일한 민트를 보유하며, 마지막 거래가 그 중 일부에만 영향을 미친 경우 지갑은 과소 계산될 수 있습니다.
매우 큰 잔액에 대한 네이티브 SOL의 정밀도. 솔잔액이 ~9,007,199 SOL (2⁵³ 램포트)을 초과하는 경우 업스트림에서 정밀도가 손실될 수 있습니다. 토큰 금액은 영향을 받지 않습니다.
time/datetime의 정밀도는 몇 초간 이동할 수 있는 검증자 보고 블록 시간에 의존합니다, 정확하고 결정적인 결과에는 slot를 사용하세요.
요청당 하나의 토큰. 다중 민트 또는 “시간 T에서의 모든 잔액” 배치 형식은 없습니다.

다음 단계

지갑 잔액

USD 값으로 지갑의 현재 토큰 및 NFT 보유량을 가져옵니다.

지갑 API 개요

모든 지갑 API 엔드포인트 및 공유 규칙.

API 참조

과거 잔액에 대한 요청 및 응답 스키마.

시작하기

데이터 스트리밍 및 이벤트 수신

데이터 API 및 RPC

거래

거래 보내기

서비스로서의 지갑

안내서

리소스

Solana 지갑의 과거 토큰 잔액 가져오는 방법

개요

사용 시기

시작하기

타임스탬프에서의 토큰 잔액

날짜 및 시간에서의 토큰 잔액

슬롯에서의 네이티브 SOL 잔액

쿼리 매개변수

날짜 및 시간 형식

응답 형식

필드 설명

사용 사례

기간 동안의 잔액 변화

스냅샷 자격 확인

모범 사례

일반 오류

한계

다음 단계

지갑 잔액

지갑 API 개요

API 참조

​개요

​사용 시기

​시작하기

​타임스탬프에서의 토큰 잔액

​날짜 및 시간에서의 토큰 잔액

​슬롯에서의 네이티브 SOL 잔액

​쿼리 매개변수

​날짜 및 시간 형식

​응답 형식

​필드 설명

​사용 사례

​기간 동안의 잔액 변화

​스냅샷 자격 확인

​모범 사례

​일반 오류

​한계

​다음 단계

지갑 잔액

지갑 API 개요

API 참조

개요

사용 시기

시작하기

타임스탬프에서의 토큰 잔액

날짜 및 시간에서의 토큰 잔액

슬롯에서의 네이티브 SOL 잔액

쿼리 매개변수

날짜 및 시간 형식

응답 형식

필드 설명

사용 사례

기간 동안의 잔액 변화

스냅샷 자격 확인

모범 사례

일반 오류

한계

다음 단계