> ## 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.
# Lấy số dư token trong quá khứ
> Lấy số dư của một token cụ thể hoặc SOL gốc trong ví tại một dấu thời gian, ngày giờ hoặc slot trước đây.
Mỗi yêu cầu tốn **100 tín dụng**.
## Tham số yêu cầu
Địa chỉ ví Solana (được mã hóa bằng base58)
Địa chỉ mint của token. Đối với SOL gốc, hãy dùng `So11111111111111111111111111111111111111111`.
Dấu thời gian Unix tính bằng **giây**. Trả về số dư tại thời điểm này. Chỉ cung cấp một trong các giá trị `time`, `datetime` hoặc `slot`.
Chuỗi ngày giờ. Các định dạng được chấp nhận: `2025-01-10` (nửa đêm theo UTC), `2025-01-10 19:20:00`,
`2025-01-10T19:20:00` (phần giây là tùy chọn) hoặc kèm múi giờ rõ ràng
(`2025-01-10T19:20:00Z`, `...+02:00`). **Được hiểu là UTC trừ khi có chỉ định
múi giờ rõ ràng.** Chỉ cung cấp một trong các giá trị `time`, `datetime` hoặc `slot`.
Số slot. Trả về số dư tại slot này. Chính xác và có tính xác định. Chỉ cung cấp một trong các giá trị `time`, `datetime` hoặc `slot`.
## OpenAPI
````yaml vi/openapi/wallet-api/openapi.yaml GET /v1/wallet/{wallet}/balance-at
openapi: 3.0.3
info:
title: Wallet API
description: >
REST API hiệu năng cao để truy vấn dữ liệu ví Solana, bao gồm số dư, lịch sử
giao dịch, chuyển khoản và thông tin danh tính.
## Xác thực
Mọi yêu cầu đều cần khóa API được truyền theo một trong hai cách:
- Tham số truy vấn: `?api-key=YOUR_API_KEY`
- Tiêu đề: `X-Api-Key: YOUR_API_KEY`
version: 1.0.0
contact:
name: Hỗ trợ API
url: https://helius.dev
servers:
- url: https://api.helius.xyz
description: Máy chủ sản xuất
security:
- ApiKeyQuery: []
- ApiKeyHeader: []
tags:
- name: Danh tính
description: Tra cứu danh tính ví và các địa chỉ đã biết
- name: Số dư
description: Truy vấn số dư token và NFT
- name: Lịch sử
description: Lịch sử giao dịch và thay đổi số dư
- name: Chuyển khoản
description: Hoạt động chuyển token
- name: Cấp vốn
description: Thông tin cấp vốn cho ví
paths:
/v1/wallet/{wallet}/balance-at:
get:
tags:
- Số dư
summary: Lấy số dư lịch sử
description: >
Truy xuất số dư của một token cụ thể (hoặc SOL gốc) trong ví tại một
thời điểm trước đây,
được chỉ định bằng dấu thời gian Unix, chuỗi ngày giờ hoặc số slot.
Số dư được đọc từ giao dịch gần nhất của ví có liên quan đến token **tại
hoặc
trước** thời điểm được yêu cầu — tức số dư sau giao dịch, theo định
nghĩa được
duy trì đến giao dịch tiếp theo của ví. Đây là giá trị chính xác, không
phải ước tính.
Phải cung cấp **chính xác một** trong các tham số `time`, `datetime`
hoặc `slot`. Giá trị `datetime`
không có múi giờ rõ ràng được hiểu là **UTC**. Để có kết quả chính xác
và xác định,
hãy dùng `slot` — thời gian khối do trình xác thực báo cáo có thể lệch
vài giây.
Đối với SOL gốc, hãy truyền pseudo-mint
`So11111111111111111111111111111111111111111` làm `mint`.
Ví không có hoạt động phù hợp tại hoặc trước thời điểm được yêu cầu
**không** phải lỗi —
endpoint trả về `200` với `balance: "0"` và `asOf: null`.
`balance` và `balanceRaw` được trả về dưới dạng **chuỗi** để tránh mất
độ chính xác với các giá trị lớn.
operationId: getWalletBalanceAt
parameters:
- $ref: '#/components/parameters/WalletAddress'
- name: mint
in: query
required: true
description: >-
Địa chỉ mint của token. Đối với SOL gốc, dùng
`So11111111111111111111111111111111111111111`.
schema:
type: string
default: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
example: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
- name: time
in: query
description: >-
Dấu thời gian Unix tính bằng **giây**. Trả về số dư tại thời điểm
này. Cung cấp chính xác một trong `time`, `datetime` hoặc `slot`.
schema:
type: integer
default: 1750000000
minimum: 0
example: 1736536800
- name: datetime
in: query
description: >
Chuỗi ngày giờ. Các định dạng được chấp nhận: `2025-01-10` (nửa đêm
UTC), `2025-01-10 19:20:00`,
`2025-01-10T19:20:00` (phần giây không bắt buộc), hoặc có múi giờ rõ
ràng
(`2025-01-10T19:20:00Z`, `...+02:00`). **Được hiểu là UTC trừ khi có
múi giờ rõ ràng.** Cung cấp chính xác một trong `time`, `datetime`
hoặc `slot`.
schema:
type: string
example: '2025-01-10 19:20:00'
- name: slot
in: query
description: >-
Số slot. Trả về số dư tại slot này. Chính xác và xác định. Cung cấp
chính xác một trong `time`, `datetime` hoặc `slot`.
schema:
type: integer
minimum: 0
example: 313000000
responses:
'200':
description: Đã truy xuất số dư lịch sử thành công
content:
application/json:
schema:
$ref: '#/components/schemas/BalanceAtResponse'
'400':
description: >-
Thiếu `mint`; mint không hợp lệ; không có hoặc có nhiều hơn một
trong `time`/`datetime`/`slot`; `time`/`slot` không phải số nguyên;
hoặc không thể phân tích `datetime`
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Phải cung cấp chính xác một trong time, datetime hoặc slot
code: 400
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Địa chỉ ví trong đường dẫn không hợp lệ
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
'502':
description: >-
Lỗi hoặc hết thời gian chờ RPC thượng nguồn. Có thể thử lại với cơ
chế lùi theo cấp số nhân.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: UPSTREAM_ERROR
code: 502
details: Yêu cầu RPC thượng nguồn không thành công. Vui lòng thử lại.
components:
parameters:
WalletAddress:
name: wallet
in: path
required: true
description: Địa chỉ ví Solana (được mã hóa base58)
schema:
type: string
pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
default: GQUtvPx89ZNCwmvQqFmH59bJcU8fW8siETpaxod7Aydz
example: GQUtvPx89ZNCwmvQqFmH59bJcU8fW8siETpaxod7Aydz
schemas:
BalanceAtResponse:
type: object
properties:
wallet:
type: string
description: Giá trị lặp lại của địa chỉ ví đã truy vấn
example: 5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9
mint:
type: string
description: >-
Giá trị lặp lại của mint đã truy vấn (pseudo-mint SOL khi là token
gốc)
example: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
isNative:
type: boolean
description: Cho biết kết quả có phải SOL gốc hay không
example: false
balance:
type: string
description: >-
Số lượng dễ đọc dưới dạng **chuỗi** thập phân (không phải số, để số
dư lớn không mất độ chính xác). Các số 0 ở cuối bị loại bỏ.
example: '284961463.392936'
balanceRaw:
type: string
description: >-
Số lượng chính xác theo đơn vị nhỏ nhất (lamport đối với SOL), dưới
dạng chuỗi
example: '284961463392936'
decimals:
type: integer
description: Số chữ số thập phân của token (9 đối với SOL)
example: 6
requested:
type: object
description: >-
Giá trị lặp lại của truy vấn. Khi dùng `datetime`, `time` cũng được
điền bằng số giây epoch đã phân giải để thể hiện cách diễn giải UTC.
properties:
time:
type: integer
nullable: true
description: >-
Thời gian được yêu cầu dưới dạng số giây epoch (cũng được đặt
khi dùng `datetime`)
example: 1736536800
slot:
type: integer
nullable: true
description: Slot được yêu cầu khi dùng `slot`
example: null
datetime:
type: string
nullable: true
description: Chuỗi ngày giờ ban đầu khi dùng `datetime`
example: null
required:
- time
- slot
- datetime
asOf:
type: object
nullable: true
description: >-
Giao dịch dùng để đọc số dư. **Là `null` khi ví không có giao dịch
phù hợp tại hoặc trước thời điểm được yêu cầu** — nghĩa là số dư
thực sự là `0` (ví chưa nắm giữ token vào thời điểm đó), không phải
lỗi.
properties:
slot:
type: integer
description: Slot của giao dịch
example: 313000000
blockTime:
type: integer
nullable: true
description: >-
Thời gian khối của giao dịch tính bằng giây Unix (có thể là
null)
example: 1736536794
signature:
type: string
description: Chữ ký giao dịch
example: 5Cyy7Mh9nVgFq3T8wJp2sKxR4dE6bA1uZoNcLrXmYqUpon
required:
- slot
- signature
required:
- wallet
- mint
- isNative
- balance
- balanceRaw
- decimals
- requested
- asOf
Error:
type: object
properties:
error:
type: string
description: Thông báo lỗi
example: Địa chỉ ví không hợp lệ
code:
type: integer
description: Mã trạng thái HTTP
example: 400
details:
type: string
description: Chi tiết bổ sung về lỗi
example: '''invalid-address'' không phải là địa chỉ Solana hợp lệ'
required:
- error
- code
responses:
Unauthorized:
description: Thiếu khóa API hoặc khóa API không hợp lệ
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Cần có khóa API. Truyền qua ?api-key=xxx hoặc tiêu đề X-Api-Key
code: 401
RateLimited:
description: Đã vượt quá giới hạn tốc độ.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: RATE_LIMIT_EXCEEDED
code: 429
details: Quá nhiều yêu cầu. Hãy thử lại sau 2 giây.
InternalError:
description: Lỗi máy chủ tạm thời. Có thể thử lại với cơ chế lùi theo cấp số nhân.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: INTERNAL_ERROR
code: 500
details: Đã xảy ra lỗi không mong muốn. Vui lòng thử lại.
securitySchemes:
ApiKeyQuery:
type: apiKey
in: query
name: api-key
description: Khóa API được truyền dưới dạng tham số truy vấn
ApiKeyHeader:
type: apiKey
in: header
name: X-Api-Key
description: Khóa API được truyền trong tiêu đề yêu cầu
````