> ## 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.

# Tổng quan về Wallet API (Beta)

> Truy vấn dữ liệu ví Solana bằng Wallet API. Lấy số dư, lịch sử giao dịch, các giao dịch chuyển, thông tin danh tính và nguồn cấp vốn trong một yêu cầu duy nhất.

<Note>
  Wallet API đang ở giai đoạn Beta. Các điểm cuối và định dạng phản hồi có thể thay đổi.
</Note>

## Wallet API là gì?

Wallet API cung cấp các điểm cuối REST cấp cao để truy vấn toàn bộ dữ liệu ví Solana — số dư, lịch sử giao dịch, giao dịch chuyển token, phân giải danh tính, số dư trong quá khứ và nguồn cấp vốn. Thay vì thực hiện nhiều lệnh gọi RPC và phân tích dữ liệu blockchain thô, bạn nhận được thông tin có cấu trúc, dễ đọc cùng mức giá theo USD trong một yêu cầu duy nhất.

API này được xây dựng cho ví, công cụ theo dõi danh mục đầu tư, trình khám phá, bộ xử lý thanh toán, công cụ thuế cũng như các hệ thống tuân thủ và AML. Tất cả điểm cuối đều dùng chung URL cơ sở `https://api.helius.xyz` và trả về số lượng theo đơn vị dễ đọc (không cần chuyển đổi lamport).

## Tại sao nên dùng Helius cho dữ liệu ví?

<CardGroup cols={2}>
  <Card title="One REST call" icon="bolt">
    Số dư, lịch sử và giao dịch chuyển có cấu trúc mà không cần ghép nối các
    phản hồi RPC thô.
  </Card>

  <Card title="USD pricing built in" icon="dollar-sign">
    Số dư token bao gồm giá trị theo USD và tổng giá trị danh mục đầu tư, lấy từ DAS.
  </Card>

  <Card title="Identity resolution" icon="address-card">
    Hơn 32.500 tài khoản và chương trình được gắn nhãn cùng hơn 21,5 triệu thẻ phân loại cho
    các sàn giao dịch, giao thức và tổ chức.
  </Card>

  <Card title="Human-readable output" icon="book-open">
    Dữ liệu rõ ràng, đã điều chỉnh theo số thập phân thay vì lamport và lệnh thô.
  </Card>
</CardGroup>

## Các điểm cuối chính

<CardGroup cols={2}>
  <Card title="Wallet Identity" icon="address-card" href="/docs/vi/wallet-api/identity">
    Xác định các ví đã biết bằng địa chỉ hoặc tên miền SNS/ANS — sàn giao dịch, giao thức,
    tổ chức.
  </Card>

  <Card title="Wallet Balances" icon="scale-balanced" href="/docs/vi/wallet-api/balances">
    Tất cả số dư token và NFT cùng giá trị theo USD, logo và siêu dữ liệu.
  </Card>

  <Card title="Historical Balance" icon="clock" href="/docs/vi/wallet-api/balance-at">
    Số dư token hoặc SOL tại một dấu thời gian, ngày giờ hoặc slot trong quá khứ.
  </Card>

  <Card title="Wallet History" icon="clock-rotate-left" href="/docs/vi/wallet-api/history">
    Toàn bộ lịch sử giao dịch cùng các thay đổi số dư của từng giao dịch.
  </Card>

  <Card title="Token Transfers" icon="arrow-right-arrow-left" href="/docs/vi/wallet-api/transfers">
    Tất cả giao dịch chuyển đến và đi cùng thông tin người gửi/người nhận.
  </Card>

  <Card title="Funding Source" icon="money-bill-transfer" href="/docs/vi/wallet-api/funded-by">
    Nguồn cấp vốn ban đầu của ví, được truy vết đến khoản SOL đầu tiên được chuyển vào.
  </Card>
</CardGroup>

## Nên sử dụng điểm cuối nào?

| Bạn cần                                            | Sử dụng                                          | Kết quả trả về                                                     |
| -------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------ |
| Xác định ví là ai (sàn giao dịch, giao thức, nhãn) | [Danh tính](/docs/vi/wallet-api/identity)             | Tên, danh mục và thẻ của các địa chỉ đã biết                       |
| Danh mục đầu tư hiện tại của ví                    | [Số dư](/docs/vi/wallet-api/balances)                 | Tất cả token và NFT cùng giá trị theo USD                          |
| Số dư tại một thời điểm trong quá khứ              | [Số dư trong quá khứ](/docs/vi/wallet-api/balance-at) | Số dư của một token hoặc SOL tại dấu thời gian/ngày giờ/slot       |
| Toàn bộ hoạt động giao dịch                        | [Lịch sử](/docs/vi/wallet-api/history)                | Các giao dịch đã phân tích cùng thay đổi số dư theo từng giao dịch |
| Chỉ các giao dịch chuyển đã gửi/nhận               | [Giao dịch chuyển](/docs/vi/wallet-api/transfers)     | Chế độ xem theo giao dịch chuyển, gồm đối tác và hướng             |
| Nguồn gốc tiền trong ví                            | [Nguồn cấp vốn](/docs/vi/wallet-api/funded-by)        | Giao dịch chuyển SOL vào đầu tiên và người gửi                     |

Tham khảo nhanh các tuyến cơ sở (URL cơ sở `https://api.helius.xyz`):

* `GET /v1/wallet/{wallet}/identity` — lấy danh tính ví bằng địa chỉ hoặc tên miền SNS/ANS
* `POST /v1/wallet/batch-identity` — tra cứu danh tính hàng loạt (tối đa 100 địa chỉ và/hoặc tên miền)
* `GET /v1/wallet/{wallet}/balances` — lấy tất cả số dư token và NFT
* `GET /v1/wallet/{wallet}/balance-at` — 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ứ
* `GET /v1/wallet/{wallet}/history` — lấy lịch sử giao dịch cùng các thay đổi số dư
* `GET /v1/wallet/{wallet}/transfers` — lấy toàn bộ hoạt động chuyển token
* `GET /v1/wallet/{wallet}/funded-by` — tìm nguồn cấp vốn ban đầu

## Xác thực

Tất cả yêu cầu Wallet API đều cần khóa API. Bạn có thể truyền khóa dưới dạng tham số truy vấn hoặc tiêu đề:

<Tabs>
  <Tab title="Query Parameter">
    ```bash theme={"system"}
    curl "https://api.helius.xyz/v1/wallet/{wallet}/balances?api-key=YOUR_API_KEY"
    ```
  </Tab>

  <Tab title="Header">
    ```bash theme={"system"}
    curl "https://api.helius.xyz/v1/wallet/{wallet}/balances" \
      -H "X-Api-Key: YOUR_API_KEY"
    ```
  </Tab>
</Tabs>

## Yêu cầu về gói dịch vụ

Các điểm cuối về danh tính và nguồn cấp vốn yêu cầu gói trả phí. Với gói Free, yêu cầu đến các điểm cuối này trả về `403 Forbidden`. Mọi điểm cuối khác đều khả dụng trên tất cả các gói, bao gồm Free.

| Điểm cuối                            | Gói Free                         |
| ------------------------------------ | -------------------------------- |
| `GET /v1/wallet/{wallet}/identity`   | `403` — chỉ dành cho gói trả phí |
| `POST /v1/wallet/batch-identity`     | `403` — chỉ dành cho gói trả phí |
| `GET /v1/wallet/{wallet}/funded-by`  | `403` — chỉ dành cho gói trả phí |
| `GET /v1/wallet/{wallet}/balances`   | Khả dụng                         |
| `GET /v1/wallet/{wallet}/balance-at` | Khả dụng                         |
| `GET /v1/wallet/{wallet}/history`    | Khả dụng                         |
| `GET /v1/wallet/{wallet}/transfers`  | Khả dụng                         |

Bất kỳ cấp trả phí nào cũng mở khóa các điểm cuối bị giới hạn — Developer, Business và mọi cấp cao hơn (chẳng hạn như Enterprise). Để bật tính năng tra cứu danh tính và nguồn cấp vốn, hãy [nâng cấp gói trong bảng điều khiển](https://dashboard.helius.dev).

## Số lượng và đơn vị

Wallet API là một lớp trừu tượng cấp cao trên dữ liệu Solana thô. Tất cả trường `amount` trong phản hồi đều **dễ đọc** — đã được chia cho `decimals` của token — vì vậy bạn có thể hiển thị trực tiếp mà không cần chuyển đổi. Các lệnh gọi RPC Solana thô trả về giá trị theo lamport (đơn vị nhỏ nhất, 10⁻⁹ SOL); Wallet API thì không. `"amount": 1.5` có nghĩa là 1,5 SOL, không phải 1,5 lamport.

Khi cần phép tính chính xác, một số điểm cuối cũng cung cấp `amountRaw`: cùng một giá trị dưới dạng số nguyên thô được tuần tự hóa thành chuỗi để tránh mất độ chính xác của số dấu phẩy động. Công thức chuyển đổi là:

`amount = parseInt(amountRaw) / 10**decimals`

| Điểm cuối                      | `amount` dễ đọc                        | Chuỗi `amountRaw` thô |
| ------------------------------ | -------------------------------------- | --------------------- |
| **Balances**                   | Trường `balance`                       | Không khả dụng        |
| **Balance-at**                 | Trường `balance` (**chuỗi** thập phân) | Trường `balanceRaw`   |
| **Funded-by**                  | Trường `amount`                        | Trường `amountRaw`    |
| **Transfers**                  | Trường `amount`                        | Trường `amountRaw`    |
| **History** (`balanceChanges`) | Trường `amount`                        | Không khả dụng        |

Sử dụng `amount` để hiển thị. Sử dụng `amountRaw` khi truyền giá trị vào các lệnh trên chuỗi hoặc những hệ thống khác yêu cầu phép tính số nguyên chính xác.

## Bắt đầu

<Steps>
  <Step title="Get your API key">
    Đăng ký tại [dashboard.helius.dev](https://dashboard.helius.dev) để nhận khóa API.
  </Step>

  <Step title="Choose your endpoint">
    Sử dụng bảng trên để chọn điểm cuối phù hợp với trường hợp sử dụng của bạn.
  </Step>

  <Step title="Make your first request">
    Bắt đầu bằng một truy vấn số dư đơn giản:

    ```bash theme={"system"}
    curl "https://api.helius.xyz/v1/wallet/86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY/balances?api-key=YOUR_API_KEY"
    ```
  </Step>

  <Step title="Handle the response">
    Phân tích phản hồi JSON và hiển thị dữ liệu trong ứng dụng của bạn.
  </Step>
</Steps>

## Các bước tiếp theo

<CardGroup cols={3}>
  <Card title="Getting Data" icon="database" href="/docs/vi/getting-data">
    Khám phá mọi cách truy vấn dữ liệu Solana trên Helius.
  </Card>

  <Card title="API Reference" icon="code" href="/docs/vi/api-reference/wallet-api">
    Lược đồ yêu cầu và phản hồi cho tất cả điểm cuối Wallet API.
  </Card>

  <Card title="Contact Support" icon="headset" href="/docs/vi/support/contact-support">
    Nhận trợ giúp qua Discord, trò chuyện hoặc email.
  </Card>
</CardGroup>