> ## 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.
# Solana 지갑의 과거 토큰 잔액 가져오는 방법
> 과거의 타임스탬프, 날짜 및 시간 또는 슬롯에서 토큰이나 네이티브 SOL의 지갑 잔액을 조회합니다. PnL, 비용 기준, 세금 신고 및 지갑 상태 재구성을 위해 이상적입니다.
지갑 API는 베타 버전입니다. 엔드포인트와 응답 형식은 변경될 수 있습니다.
## 개요
과거 잔액 엔드포인트는 질문에 답합니다: **과거 특정 시점에 이 지갑의 특정 토큰 (또는 네이티브 SOL) 잔액은 얼마였습니까?** [Balances](/docs/ko/wallet-api/balances) 엔드포인트가 *현재* 보유량을 보고하는 동안, `balance-at`는 어느 타임스탬프, 날짜 및 시간 또는 슬롯에서든 보유량을 보고합니다.
이 엔드포인트는 지갑 및 토큰과 관련된 **요청한 시점 직전 또는 해당 시점의 가장 최근 거래**를 찾아 해당 거래의 **거래 후 잔액**을 읽습니다. 거래의 거래 후 잔액은 그 거래부터 다음 거래까지 유지된 잔액이므로, "시점 T에서의 잔액"은 T 시점 직전 또는 동일한 블록 시간 (또는 슬롯)에서 마지막 관련 거래의 거래 후 잔액입니다. 일반적인 지갑의 경우, 이는 추정치가 아닌 정확한 값입니다.
* **토큰 (SPL / Token-2022)**: 거래의 포스트 토큰 잔액에서 읽으며, 지갑의 토큰 계좌가 가지고 있는 그것들을 합산합니다.
* **네이티브 SOL**: 거래의 램포트 포스트 잔액에서 읽습니다. 네이티브 SOL은 가상 민트 `So11111111111111111111111111111111111111111`로 주소를 지정합니다.
## 사용 시기
다음 상황에서 과거 잔액 API를 사용하세요:
* **PnL 계산**: 기간 시작과 종료 시 보유량 확인.
* **비용 기준 및 세금 항목**: 취득 또는 처분 이벤트 시 잔액 재구성.
* **분쟁 해결**: 특정 순간에 지갑이 무엇을 보유했는지 증명.
* **스냅샷 확인**: 에어드롭 또는 거버넌스 스냅샷에서 지갑의 잔액 확인.
* **회계 및 감사**: 기간 경계에서 지갑 상태 재구성.
## 시작하기
### 타임스탬프에서의 토큰 잔액
유닉스 타임스탬프에서 지갑의 USDC 잔액을 가져옵니다:
```javascript theme={"system"}
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
);
```
```python theme={"system"}
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
)
```
```bash theme={"system"}
curl "https://api.helius.xyz/v1/wallet/5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9/balance-at?mint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&time=1736536800&api-key=YOUR_API_KEY"
```
### 날짜 및 시간에서의 토큰 잔액
타임스탬프 대신 사람이 읽을 수 있는 날짜 및 시간을 전달하세요. 공간을 `%20`로 URL 인코딩하는 것을 기억하세요:
```bash theme={"system"}
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`를 사용하세요. 슬롯 기반 쿼리는 정확하고 결정적입니다:
```bash theme={"system"}
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` 필드는 해석된 시대 초를 보여주므로 해석을 확인할 수 있습니다.
## 응답 형식
```json theme={"system"}
{
"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`를 반환합니다 — 지갑은 그때까지 토큰을 보유한 적이 없었던 것입니다.
## 사용 사례
### 기간 동안의 잔액 변화
두 시점 간의 보유량 비교:
```javascript theme={"system"}
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 };
};
```
### 스냅샷 자격 확인
스냅샷 슬롯에서 지갑이 토큰을 보유했는지 확인:
```javascript theme={"system"}
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 엔드포인트 및 공유 규칙.
과거 잔액에 대한 요청 및 응답 스키마.