Skip to main content
Wallet API đang ở giai đoạn Beta. Các endpoint và định dạng phản hồi có thể thay đổi.

Tổng quan

Endpoint Wallet Balances truy xuất toàn bộ token và NFT mà một ví Solana nắm giữ — SOL, token SPL, Token-2022 và NFT — kèm theo giá USD, logo và siêu dữ liệ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á. Endpoint trả về tối đa 100 token cho mỗi yêu cầu, vì vậy bạn cần phân trang thủ công. Sử dụng tham số page để lấy các trang bổ sung và đọc pagination.hasMore để biết khi nào còn kết quả. Mỗi yêu cầu là một lệnh gọi API và tốn 100 credit.
Giá USD được lấy từ DAS và cập nhật mỗi giờ, bao phủ 10.000 token hàng đầu theo vốn hóa thị trường. pricePerToken và usdValue là null đối với các token không được hỗ trợ. Giá chỉ là ước tính, không phải giá thị trường theo thời gian thực.

Khi nào nên sử dụng

Sử dụng Wallet Balances API khi cần:
  • Hiển thị tài sản trong danh mục đầu tư: cho người dùng xem toàn bộ token và NFT họ đang nắm giữ.
  • Tính giá trị USD: lấy định giá danh mục đầu tư với dữ liệu giá được cập nhật mỗi giờ.
  • Xây dựng giao diện ví: cung cấp dữ liệu cho bảng điều khiển ví và danh sách tài sản.
  • Theo dõi lượng token nắm giữ: giám sát số dư của các token cụ thể trên nhiều ví.
  • Phân tích danh mục đầu tư: phân tích mức độ phân bổ và tập trung tài sản.
  • Báo cáo thuế: tạo bản chụp tài sản nắm giữ phục vụ mục đích thuế.

Bắt đầu nhanh

Truy vấn số dư cơ bản

Lấy toàn bộ số dư token của một ví kèm theo giá trị USD:

Bao gồm NFT trong kết quả

Lấy cả token và NFT trong một yêu cầu bằng showNfts=true:

Lọc kết quả

Sử dụng các tham số truy vấn để thu hẹp dữ liệu trả về:

Tham số truy vấn

Định dạng phản hồi

Ghi chú về trường

  • balance: số lượng dễ đọc, đã được điều chỉnh theo số chữ số thập phân — 1.5 có nghĩa là 1,5 SOL và 1000.5 có nghĩa là 1000,5 USDC. Không cần chuyển đổi lamport. Endpoint này không cung cấp trường amountRaw thô; nếu cần giá trị số nguyên chính xác, hãy tính giá trị đó dưới dạng Math.round(balance * 10 ** decimals).
  • decimals: chỉ được cung cấp để tham khảo.
  • pricePerToken / usdValue: null đối với các token không có dữ liệu giá từ DAS (xem ghi chú về giá ở trên).
  • totalUsdValue: tổng giá trị USD chỉ dành cho trang phản hồi hiện tại. Để tính giá trị của toàn bộ danh mục đầu tư, hãy duyệt qua tất cả các trang và cộng usdValue của từng số dư.
  • tokenProgram: tiêu chuẩn token mà mỗi token sử dụng — spl-token (SPL Token cũ) hoặc token-2022 (Token Extensions). Cả hai đều được hỗ trợ đầy đủ.

Trường hợp sử dụng

Xây dựng bảng điều khiển danh mục đầu tư

Hiển thị tài sản người dùng nắm giữ kèm theo giá trị USD:

Tính mức độ tập trung token

Phân tích mức độ đa dạng hóa danh mục đầu tư:

Theo dõi số dư của một token cụ thể

Giám sát một token cụ thể trên nhiều ví:

Xuất dữ liệu tài sản nắm giữ để báo cáo thuế

Tạo bản chụp tài sản nắm giữ:

Phân trang

Đối với ví có hơn 100 token, hãy duyệt qua các trang kết quả bằng tham số page và pagination.hasMore:
NFT chỉ được trả về ở trang đầu tiên (tối đa 100), bất kể cách phân trang token.

Phương pháp hay nhất

  • Lọc số dư bằng 0 để giao diện gọn gàng hơn. Sử dụng showZeroBalance=false để ẩn các token mà ví không còn nắm giữ.
  • Chỉ bao gồm NFT khi cần. NFT bị loại trừ theo mặc định để tối ưu hiệu suất; chỉ đặt showNfts=true khi cần hiển thị chúng.
  • Xử lý trường hợp thiếu dữ liệu giá. Luôn kiểm tra xem pricePerToken và usdValue có phải là null hay không trước khi hiển thị. Đây là các giá trị ước tính được cập nhật mỗi giờ từ DAS, không phải giá thị trường theo thời gian thực.
  • Lưu phản hồi vào bộ nhớ đệm. Dữ liệu số dư có thể được lưu vào bộ nhớ đệm trong vài giây để giảm số lệnh gọi API.
  • Phân trang cho ví lớn. Một số ví nắm giữ hàng nghìn token; hãy triển khai tính năng phân trang để xử lý hiệu quả.

Lỗi thường gặp

Các bước tiếp theo

Historical Balance

Lấy số dư token hoặc SOL tại một dấu thời gian, ngày giờ hoặc slot trong quá khứ.

Wallet API Overview

Tất cả các endpoint của Wallet API và các quy ước dùng chung.

API Reference

Lược đồ yêu cầu và phản hồi cho số dư ví.