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

# 钱包API概述（测试版）

> 通过钱包API查询Solana钱包数据。在单个请求中获取余额、交易历史、转账、身份信息和资金来源。

<Note>
  Wallet API处于Beta阶段。端点和响应格式可能会更改。
</Note>

## 什么是钱包 API？

钱包 API 提供用于查询完整 Solana 钱包数据的高级 REST 端点——余额、交易历史、代币转账、身份解析、历史余额和资金来源。无需进行多次 RPC 调用和解析原始区块链数据，只需一次请求即可获取结构化、可读的信息以及美元定价。

它专为钱包、投资组合跟踪器、浏览器、支付处理器、税务工具和合规与反洗钱系统构建。所有端点共享基础 URL `https://api.helius.xyz`，并返回可读单位（无需 lamport 转换）。

## 为什么选择 Helius 的钱包数据？

<CardGroup cols={2}>
  <Card title="一个REST调用" icon="bolt">
    结构化余额、历史和转账，无需拼接原始RPC响应。
  </Card>

  <Card title="内置USD定价" icon="dollar-sign">
    令牌余额包括USD值和投资组合总额，来源于DAS。
  </Card>

  <Card title="身份解析" icon="address-card">
    超过32,500个标记账户和程序，以及超过21.5M个交易所、协议和机构的类别标签。
  </Card>

  <Card title="人类可读的输出" icon="book-open">
    清晰的、经过小数调整的数据，而非原始lamports和指令。
  </Card>
</CardGroup>

## 关键端点

<CardGroup cols={2}>
  <Card title="钱包身份" icon="address-card" href="/zh/wallet-api/identity">
    通过地址或SNS/ANS域识别已知钱包——交易所、协议、机构。
  </Card>

  <Card title="钱包余额" icon="scale-balanced" href="/zh/wallet-api/balances">
    所有令牌和NFT余额，包含USD值、标识和元数据。
  </Card>

  <Card title="历史余额" icon="clock" href="/zh/wallet-api/balance-at">
    过去时间戳、日期时间或插槽的令牌或SOL余额。
  </Card>

  <Card title="钱包历史" icon="clock-rotate-left" href="/zh/wallet-api/history">
    完整的交易历史，每笔交易的余额变化。
  </Card>

  <Card title="令牌转账" icon="arrow-right-arrow-left" href="/zh/wallet-api/transfers">
    所有进出转账，包含发送者/接收者信息。
  </Card>

  <Card title="资金来源" icon="money-bill-transfer" href="/zh/wallet-api/funded-by">
    追踪钱包的原始资金来源到其首笔SOL收入。
  </Card>
</CardGroup>

## 我应该使用哪个端点？

| 你需要             | 使用此功能                             | 返回                       |
| --------------- | --------------------------------- | ------------------------ |
| 钱包身份（交易所、协议、标签） | [身份](/zh/wallet-api/identity)     | 已知地址的名称、类别和标签            |
| 钱包的当前投资组合       | [余额](/zh/wallet-api/balances)     | 所有令牌和NFT，包含USD值          |
| 过去某个时间点的余额      | [历史余额](/zh/wallet-api/balance-at) | 某一时间戳/日期时间/插槽的单个令牌或SOL余额 |
| 完整的交易活动         | [历史](/zh/wallet-api/history)      | 解析过的交易，每笔交易的余额变动         |
| 仅发送/接收的转账       | [转账](/zh/wallet-api/transfers)    | 转账级别视图，含交易对手和方向          |
| 钱包资金的来源         | [资金来源](/zh/wallet-api/funded-by)  | 首次收入的SOL转账及其发送者          |

基础路由的快速参考（基本 URL `https://api.helius.xyz`）：

* `GET /v1/wallet/{wallet}/identity` — 通过地址或SNS/ANS域获取钱包身份
* `POST /v1/wallet/batch-identity` — 批量身份查找（最多100个地址和/或域）
* `GET /v1/wallet/{wallet}/balances` — 获取所有代币和NFT余额
* `GET /v1/wallet/{wallet}/balance-at` — 获取过去时间戳、日期时间或插槽的代币或SOL余额
* `GET /v1/wallet/{wallet}/history` — 获取带余额变化的交易历史
* `GET /v1/wallet/{wallet}/transfers` — 获取所有代币转账活动
* `GET /v1/wallet/{wallet}/funded-by` — 找到原始资金来源

## 认证

所有钱包API请求都需要API密钥。您可以将其作为查询参数或头传递：

<Tabs>
  <Tab title="查询参数">
    ```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>

## 计划要求

身份和资金来源端点需要付费计划。在免费计划中，对这些端点的请求将返回 `403 Forbidden`。所有其他端点在所有计划中都是开放的，包括免费计划。

| 端点                                   | 免费计划           |
| ------------------------------------ | -------------- |
| `GET /v1/wallet/{wallet}/identity`   | `403` — 仅限付费计划 |
| `POST /v1/wallet/batch-identity`     | `403` — 仅限付费计划 |
| `GET /v1/wallet/{wallet}/funded-by`  | `403` — 仅限付费计划 |
| `GET /v1/wallet/{wallet}/balances`   | 可用             |
| `GET /v1/wallet/{wallet}/balance-at` | 可用             |
| `GET /v1/wallet/{wallet}/history`    | 可用             |
| `GET /v1/wallet/{wallet}/transfers`  | 可用             |

任何付费层都可以解锁受限端点 —— 开发者、商业和更高级别（如企业）。要启用身份和资金来源查询，[请在仪表板中升级您的计划](https://dashboard.helius.dev)。

## 金额和单位

Wallet API 是对原始 Solana 数据的高级抽象。响应中的所有 `amount` 字段都是**可读的** —— 已除以令牌的 `decimals` —— 因此您可以直接显示它们而无需任何转换。原始 Solana RPC 调用返回的值是 lamports（最小单位，10⁻⁹ SOL）；而 Wallet API 不是。`"amount": 1.5` 表示 1.5 SOL，而不是 1.5 lamports。

在需要精确算术的情况下，一些端点也会暴露 `amountRaw`：与原始整数相同的值，作为字符串序列化以避免浮点精度丢失。转换公式为：

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

| 端点                             | 可读 `amount`              | 原始 `amountRaw` 字符串 |
| ------------------------------ | ------------------------ | ------------------ |
| **Balances**                   | `balance` 字段             | 不可用                |
| **Balance-at**                 | `balance` 字段（十进制**字符串**) | `balanceRaw` 字段    |
| **Funded-by**                  | `amount` 字段              | `amountRaw` 字段     |
| **Transfers**                  | `amount` 字段              | `amountRaw` 字段     |
| **History** (`balanceChanges`) | `amount` 字段              | 不可用                |

使用 `amount` 进行显示。当将值传递给链上指令或需要精确整数算术的其他系统时，使用 `amountRaw`。

## 入门

<Steps>
  <Step title="获取您的 API 密钥">
    在 [dashboard.helius.dev](https://dashboard.helius.dev) 注册以获取您的 API 密钥。
  </Step>

  <Step title="选择您的端点">
    使用上表选择匹配您使用案例的端点。
  </Step>

  <Step title="发起您的第一个请求">
    从一个简单的余额查询开始：

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

  <Step title="处理响应">
    解析 JSON 响应，并在您的应用程序中显示数据。
  </Step>
</Steps>

## 下一步

<CardGroup cols={3}>
  <Card title="获取数据" icon="database" href="/zh/getting-data">
    探索在 Helius 上查询 Solana 数据的每种方式。
  </Card>

  <Card title="API 参考" icon="code" href="/zh/api-reference/wallet-api">
    所有 Wallet API 端点的请求和响应模式。
  </Card>

  <Card title="联系支持" icon="headset" href="/zh/support/contact-support">
    通过 Discord、聊天或电子邮件获得帮助。
  </Card>
</CardGroup>