# 주소의 스테이블코인 잔액과 거래량은 어떻게 읽습니까?

주소 · 인덱싱된 스테이블코인별 실시간 balanceOf, 그리고 기간별·전체 기간의 정산된 입출금 달러 금액

*API 가이드 · 7분 · 중급 · 개발자 · GET …/balances · GET …/volume*

`/v1/addresses/{address}/balances?chain=`은 요청 시점에 인덱싱된 모든 스테이블코인의 `balanceOf`를 체인에서 실시간으로 읽어, 실제 0을 포함한 전부를 최소 단위 문자열과 `decimals`로 나열합니다. `/v1/addresses/{address}/volume?chain=&days=`는 일별 집계에서 정산된 입출금 달러 금액을 답합니다. `days`에 걸친 `period`(기본값 30, 최대 3,650)와 `all_time`이며, 각 합계에는 `*_complete` 플래그가 있어 수치나 0을 믿기 전에 반드시 확인해야 합니다. 발행, 소각, 자기 자신에게 보낸 전송, 1달러 그래프 하한 미만의 일별 쌍은 제외됩니다. 거래량은 정산이지, 모든 Transfer 로그의 합이 아닙니다.

## 잔액

```
curl -s 'https://stablescan.achivx.com/v1/addresses/0x28C6c06298d514Db089934071355E5743bf21d60/balances?chain=1'
```

2026-10-24, 이더리움(Ethereum)의 바이낸스(Binance) 핫월렛입니다(행 일곱 개 중 세 개 표시).

```
{
  "chain_id": 1,
  "address": "0x28C6c06298d514Db089934071355E5743bf21d60",
  "items": [
    {"symbol": "USDT", "token": "0xdac17f958d2ee523a2206206994597c13d831ec7", "decimals": 6,  "balance": "567667828814321"},
    {"symbol": "USD1", "token": "0x8d0d000ee44948fc98c9b98a4fa4921476f08b0d", "decimals": 18, "balance": "12634092351409304697742144"},
    {"symbol": "USDe", "token": "0x4c9edd5852cd905f086c759e8383e09bff1e68b3", "decimals": 18, "balance": "11226265557419218882322902"}
  ],
  "is_contract": false,
  "note": "Live on-chain ERC-20 balanceOf of this address for each indexed stablecoin, read at the latest block via the RPC pool at request time (Class-F fact, not a heuristic). Every indexed stablecoin is listed with its balance, INCLUDING a genuine zero …",
  "chain_source": "explicit",
  "freshness_seconds": 205
}
```

`decimals: 6`인 `567667828814321`은 567,667,828.81 USDT이고, 18인 `12634092351409304697742144`는 12,634,092.35 [USD1](https://achivx.kr/academy/issuers/bitgo/)입니다. 잔액은 의도적으로 **문자열**입니다. double이 정확히 담을 수 있는 범위를 넘기 때문입니다. 정수 타입(Python의 `int`, Go의 `*big.Int`, TypeScript의 `BigInt`)으로 파싱하고, `10**decimals`로 나누는 것은 표시할 때만 하십시오.

이것은 `address`에 여러분이 입력한 표기를 그대로 돌려주는 유일한 주소 라우트입니다(다른 라우트는 체인 자체의 표기로 다시 씁니다). `is_contract`는 주소가 코드인지 알려 줍니다. `Cache-Control: public, max-age=30`.

[첫 요청](https://achivx.kr/academy/api/first-request/)의 세 가지 헬퍼로 같은 호출을 하면 다음과 같습니다.

**Python**

```
bal = scan(f"/v1/addresses/{addr}/balances", chain=1)
for row in bal["items"]:
    units = int(row["balance"])
    if units:
        print(row["symbol"], units / 10 ** row["decimals"])
```

**Go**

```
var bal struct {
	Items []struct {
		Symbol   string `json:"symbol"`
		Decimals int    `json:"decimals"`
		Balance  string `json:"balance"`
	} `json:"items"`
}
if err := get("/v1/addresses/"+addr+"/balances", url.Values{"chain": {"1"}}, &bal); err != nil {
	return err
}
for _, row := range bal.Items {
	units, _ := new(big.Int).SetString(row.Balance, 10)
	if units.Sign() != 0 {
		fmt.Println(row.Symbol, units, "minor units,", row.Decimals, "decimals")
	}
}
```

**TypeScript**

```
type Balances = { items: { symbol: string; token: string; decimals: number; balance: string }[]; is_contract: boolean };
const bal = await scan<Balances>(`/v1/addresses/${addr}/balances`, { chain: 1 });
for (const row of bal.items) {
  const units = BigInt(row.balance);
  if (units !== 0n) console.log(row.symbol, units, "minor units,", row.decimals, "decimals");
}
```

## 거래량

```
curl -s 'https://stablescan.achivx.com/v1/addresses/0x28C6c06298d514Db089934071355E5743bf21d60/volume?chain=1&days=30'
```

```
{
  "address": "0x28c6c06298d514db089934071355e5743bf21d60",
  "chain_id": 1,
  "all_time": {"in_usd6": 51212686119569437, "out_usd6": 51776095888785117, "total_usd6": 102988782008354554, "transfers": 3205310},
  "period":   {"in_usd6": 17085867659507583, "out_usd6": 18464258443073691, "total_usd6": 35550126102581274, "transfers": 1086498},
  "period_days": 30,
  "period_complete": true,
  "all_time_complete": true,
  "since_day": "2026-07-22",
  "note": "Settled payment volume from the daily edge rollup, normalized to US dollars (USDC==USD, peg 1). Mints and burns are excluded (0x0 is not a counterparty), as are day-pairs under the $1 graph floor — this is not the sum of every Transfer log. Finalized rows only …",
  "freshness_seconds": 198
}
```

30일 동안 입금 171억 달러, 출금 185억 달러, 전체 기간 1,030억 달러, 전송 320만 건입니다. `since_day: "2026-07-22"`는 이 네트워크의 집계에서 *전체 기간*이 어디서 시작하는지 알려 줍니다. 두 `*_complete` 플래그가 모두 `true`이므로 합계는 실제 합계입니다. 허브 규모의 주소에서는 조회가 예산을 다 쓸 수 있으며, 그때 `period_complete: false`는 *최소한 이만큼*을 뜻합니다. 제재 대상 예시는 모든 필드에 0을 답하고 두 플래그 모두 `true`였습니다. 측정된 없음이며, 측정되지 않은 없음과는 다릅니다.

`days`는 1부터 3,650까지이며, 그 밖의 값은 `400 invalid_days`입니다. 솔라나(Solana)에서는 응답에 주소의 채움 상태인 `coverage_status`(`pending` 또는 `partial`)도 포함됩니다. `*_complete` 플래그는 요청 예산만 설명할 뿐 채움 상태는 절대 설명하지 않으며, `coverage_status`가 없는 솔라나 응답은 그것을 제때 읽지 못한 것이므로 `pending`으로 취급하십시오.

[첫 요청](https://achivx.kr/academy/api/first-request/)의 세 가지 헬퍼로 같은 호출을 하면 다음과 같습니다.

**Python**

```
vol = scan(f"/v1/addresses/{addr}/volume", chain=1, days=90)
if not vol["period_complete"]:
    print("floor, not total:")
print(f'in ${vol["period"]["in_usd6"] / 1e6:,.0f}  out ${vol["period"]["out_usd6"] / 1e6:,.0f}  over {vol["period_days"]} days')
```

**Go**

```
var vol struct {
	Period struct {
		InUSD6    int64 `json:"in_usd6"`
		OutUSD6   int64 `json:"out_usd6"`
		TotalUSD6 int64 `json:"total_usd6"`
		Transfers int64 `json:"transfers"`
	} `json:"period"`
	PeriodDays     int  `json:"period_days"`
	PeriodComplete bool `json:"period_complete"`
}
if err := get("/v1/addresses/"+addr+"/volume", url.Values{"chain": {"1"}, "days": {"90"}}, &vol); err != nil {
	return err
}
fmt.Printf("in $%.0f out $%.0f over %d days (complete: %v)\n", float64(vol.Period.InUSD6)/1e6, float64(vol.Period.OutUSD6)/1e6, vol.PeriodDays, vol.PeriodComplete)
```

**TypeScript**

```
type Volume = { period: { in_usd6: number; out_usd6: number; total_usd6: number; transfers: number }; period_days: number; period_complete: boolean; all_time_complete: boolean };
const vol = await scan<Volume>(`/v1/addresses/${addr}/volume`, { chain: 1, days: 90 });
console.log(`in $${(vol.period.in_usd6 / 1e6).toFixed(0)} out $${(vol.period.out_usd6 / 1e6).toFixed(0)}`, vol.period_complete ? "" : "(floor, not total)");
```

## 거래량은 정산이고, 잔액은 현재입니다

두 라우트는 서로 다른 질문에 답하며, 설계상 값이 일치하지 않습니다. 잔액은 최신 블록에서 체인 자체의 `balanceOf`입니다. 거래량은 일별 집계가 정산으로 센 것입니다. 확정된 행만 포함하며, [발행](https://achivx.kr/academy/reference/glossary/#g-mint-burn)과 소각(`0x0`은 거래 상대가 아닙니다), 자기 자신에게 보낸 전송, 1달러 그래프 하한 미만의 일별 쌍을 제외하고, 페그 1로 달러 환산합니다. 같은 날 USDC 1,000달러를 받아 그대로 보낸 주소는 잔액이 0이고 거래량이 2,000달러입니다. 어느 쪽도 위험 신호가 아닙니다.

## Stablecoin scanner ACHIVX에서

- 예시의 실시간 잔액: [/v1/addresses/0x28C6…1d60/balances?chain=1](https://stablescan.achivx.com/v1/addresses/0x28C6c06298d514Db089934071355E5743bf21d60/balances?chain=1); 30일 거래량: [/volume?chain=1&days=30](https://stablescan.achivx.com/v1/addresses/0x28C6c06298d514Db089934071355E5743bf21d60/volume?chain=1&days=30).
- 페이지의 같은 수치 — [/ethereum/address/0x28C6…1d60](https://stablescan.achivx.com/ethereum/address/0x28C6c06298d514Db089934071355E5743bf21d60)의 잔액 블록과 사실 요약 줄.

## 출처

- [REST 인터페이스의 OpenAPI 3.1 명세(API 1.4.0)](https://stablescan.achivx.com/openapi.json)
- [GET /v1/methodology (stablscan-methodology-v0.5.0)](https://stablescan.achivx.com/v1/methodology)
- [GET /v1/addresses/0x28C6…1d60/balances?chain=1 (2026-10-24 조회)](https://stablescan.achivx.com/v1/addresses/0x28C6c06298d514Db089934071355E5743bf21d60/balances?chain=1)

## 더 알아보기

- [가이드: 주소 페이지](https://achivx.kr/academy/guides/address-page/)
- [정산 거래량의 의미](https://achivx.kr/academy/how-it-works/what-settled-volume-means/)
- [정직한 숫자](https://achivx.kr/academy/concepts/honest-numbers/)

## 관련 질문

- [주소가 제재 대상인지, 동결되었는지, 알려진 서비스인지 어떻게 확인합니까?](https://achivx.kr/academy/api/address-overview/)
- [정산 피드는 어떻게 읽고, 주소·토큰·블록으로 어떻게 필터링합니까?](https://achivx.kr/academy/api/settlement-feed/)
- [모든 호출이 따르는 규칙은 무엇입니까?](https://achivx.kr/academy/api/the-rules-every-call-follows/)

주소 · GET …/balances · GET …/volume · 2026-10-24 작성, openapi.json, agents.md 및 당일 실제 호출 기준. 응답 형태는 인용이며, 수치는 날짜 기준이고 인덱스에 따라 달라집니다.

---

출처: https://achivx.kr/academy/api/address-balances-and-volume/ · 영어 원문: https://achivx.com/academy/api/address-balances-and-volume.html