> ## 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ư ví
> Truy xuất số dư token và lượng SOL nắm giữ của một địa chỉ ví Solana.
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)
Số trang dùng để phân trang (bắt đầu từ 1)
Số lượng token tối đa trên mỗi trang
Bao gồm các token có số dư bằng 0
Bao gồm SOL gốc trong kết quả
Bao gồm NFT trong kết quả (tối đa 100, chỉ ở trang đầu tiên)
## OpenAPI
````yaml vi/openapi/wallet-api/openapi.yaml GET /v1/wallet/{wallet}/balances
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}/balances:
get:
tags:
- Số dư
summary: Lấy số dư ví
description: >
Truy xuất số dư token và NFT của một ví. **Phân trang thủ công** - API
trả về tối đa 100 token mỗi yêu cầu.
Kết quả được sắp xếp theo giá trị USD giảm dần. Token có dữ liệu giá
xuất hiện trước, sau đó là token không có giá.
**Phân trang:** Dùng tham số `page` để tải thêm trang. Phản hồi bao gồm
`pagination.hasMore`
để cho biết còn kết quả hay không. Mỗi yêu cầu thực hiện một lệnh gọi
API và tốn 100 credit.
operationId: getWalletBalances
parameters:
- $ref: '#/components/parameters/WalletAddress'
- name: page
in: query
description: Số trang dùng để phân trang (bắt đầu từ 1)
schema:
type: integer
minimum: 1
default: 1
example: 1
- name: limit
in: query
description: Số token tối đa trên mỗi trang
schema:
type: integer
minimum: 1
maximum: 100
default: 100
example: 100
- name: showZeroBalance
in: query
description: Bao gồm token có số dư bằng 0
schema:
type: boolean
default: false
- name: showNative
in: query
description: Bao gồm SOL gốc trong kết quả
schema:
type: boolean
default: true
- name: showNfts
in: query
description: Bao gồm NFT trong kết quả (tối đa 100, chỉ trang đầu tiên)
schema:
type: boolean
default: false
responses:
'200':
description: Đã truy xuất số dư ví thành công
content:
application/json:
schema:
$ref: '#/components/schemas/BalancesResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
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:
BalancesResponse:
type: object
properties:
balances:
type: array
items:
$ref: '#/components/schemas/TokenBalance'
description: >
Mảng số dư token của trang hiện tại, bao gồm SOL gốc.
Khi showNative=true, SOL xuất hiện dưới dạng phần tử đầu tiên với
địa chỉ mint So11111111111111111111111111111111111111112.
Các token khác được sắp xếp theo giá trị USD (giảm dần).
nfts:
type: array
items:
$ref: '#/components/schemas/Nft'
description: >-
Mảng NFT đang nắm giữ (chỉ được bao gồm nếu showNfts=true, tối đa
100, chỉ trang đầu tiên)
totalUsdValue:
type: number
description: >-
Tổng giá trị USD của số dư trên trang này (không phải tổng giá trị
danh mục)
example: 217.98
pagination:
type: object
description: >-
Siêu dữ liệu phân trang. Người dùng phải yêu cầu thủ công các trang
bổ sung bằng tham số page.
properties:
page:
type: integer
description: Số trang hiện tại
example: 1
limit:
type: integer
description: Số mục trên mỗi trang
example: 100
hasMore:
type: boolean
description: True nếu còn kết quả. Tăng tham số page để tải trang tiếp theo.
example: true
required:
- page
- limit
- hasMore
required:
- balances
- totalUsdValue
- pagination
TokenBalance:
type: object
properties:
mint:
type: string
description: Địa chỉ mint của token
example: So11111111111111111111111111111111111111112
symbol:
type: string
nullable: true
description: Ký hiệu token
example: SOL
name:
type: string
nullable: true
description: Tên token
example: Solana
balance:
type: number
description: Số dư token (đã điều chỉnh theo số chữ số thập phân)
example: 1.5
decimals:
type: integer
description: Số chữ số thập phân
example: 9
pricePerToken:
type: number
nullable: true
description: Giá mỗi token tính bằng USD
example: 145.32
usdValue:
type: number
nullable: true
description: Tổng giá trị nắm giữ tính bằng USD
example: 217.98
logoUri:
type: string
nullable: true
description: URL đến hình ảnh logo token
example: https://example.com/sol-logo.png
tokenProgram:
type: string
enum:
- spl-token
- token-2022
description: >-
Loại chương trình token (spl-token cho tiêu chuẩn cũ, token-2022 cho
tiêu chuẩn mới)
example: spl-token
required:
- mint
- balance
- decimals
- tokenProgram
Nft:
type: object
properties:
mint:
type: string
description: Địa chỉ mint của NFT
example: 7Xq8wXyXVqfBPPqVJjPDwG9zN5wCVxBYZ6z7vPYBzr6F
name:
type: string
nullable: true
description: Tên NFT
example: Degen Ape
imageUri:
type: string
nullable: true
description: URI hình ảnh NFT
example: https://example.com/nft.png
collectionName:
type: string
nullable: true
description: Tên bộ sưu tập
example: Degen Ape Academy
collectionAddress:
type: string
nullable: true
description: Địa chỉ bộ sưu tập
example: DegN1dXmU2uYa4n7U9qTh7YNYpK4u8L9qXx7XqYqJfGH
compressed:
type: boolean
description: Cho biết đây có phải NFT nén hay không
example: false
required:
- mint
- compressed
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:
BadRequest:
description: Tham số yêu cầu không hợp lệ
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Địa chỉ ví không hợp lệ
code: 400
details: '''invalid-address'' không phải là địa chỉ Solana hợp lệ'
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
````