---
title: ZEPETO.Currency
slug: world-sdk-guide-ch/zepetocurrency
docTags: 
createdAt: 2026-09-04T05:55:39.302Z
---

| 类型                                            | 说明                                                                                        |
| --------------------------------------------- | ----------------------------------------------------------------------------------------- |
| [BalanceRecord](./#balancerecord)             | 指定货币的余额信息。                                                                                |
| [BalanceResponse](./#balanceresponse)         | `BalanceResponse` 类提供 API 调用结果以及余额信息。                                                     |
| [BalanceListResponse](./#balancelistresponse) | `BalanceListResponse` 类提供 API 调用结果以及余额信息列表。                                               |
| [CurrencyService](./#currencyservice)         | `CurrencyService` 用于管理与 ZEPETO World 货币相关的操作。 该服务使玩家能够查询 ZEPETO 官方货币（ZEM）以及 World 内货币的余额。 |
| [CurrencyError](./#currencyerror)             | 表示货币相关请求失败原因的错误代码。                                                                        |

## BalanceRecord

`class`

指定货币的余额信息。

### 属性

| 名称         | 类型       | 说明                                          |
| ---------- | -------- | ------------------------------------------- |
| currencyId | `string` | World 内货币的 ID。若为 ZEPETO 官方货币（ZEM），则设置为空字符串。 |
| quantity   | `bigint` | 玩家在该货币上的余额。                                 |

## BalanceResponse

`class` · extends `ProductBaseResponse`

`BalanceResponse` 类提供 API 调用结果以及余额信息。

### 属性

| 名称       | 类型                                | 说明    |
| -------- | --------------------------------- | ----- |
| currency | [BalanceRecord](./#balancerecord) | 余额信息。 |

## BalanceListResponse

`class` · extends `ProductBaseResponse`

`BalanceListResponse` 类提供 API 调用结果以及余额信息列表。

### 属性

| 名称         | 类型                           | 说明                                |
| ---------- | ---------------------------- | --------------------------------- |
| currencies | `Dictionary<string, bigint>` | 将 World 内货币 ID 与玩家在各货币上的余额相映射的集合。 |

## CurrencyService

`class`

`CurrencyService` 用于管理与 ZEPETO World 货币相关的操作。
该服务使玩家能够查询 ZEPETO 官方货币（ZEM）以及 World 内货币的余额。

### 方法

### GetUserCurrencyBalancesAsync

`static GetUserCurrencyBalancesAsync() → BaseRequest<BalanceListResponse>`

该异步方法用于获取所有已定义的 World 内货币的余额信息。

**返回值：** `BaseRequest<BalanceListResponse>` — 一个 `BaseRequest` 对象。异步处理完成后，可通过 `responseData` 属性访问 `BalanceListResponse` 对象。

### GetUserCurrencyBalanceAsync

`static GetUserCurrencyBalanceAsync(currencyId: string) → BaseRequest<BalanceResponse>`

该异步方法根据提供的货币 ID 获取指定 World 内货币的余额。

| 参数         | 类型       | 说明        |
| ---------- | -------- | --------- |
| currencyId | `string` | 要获取的货币 ID |

**返回值：** `BaseRequest<BalanceResponse>` — 一个 `BaseRequest` 对象。异步处理完成后，可通过 `responseData` 属性访问 `BalanceResponse` 对象。

### GetOfficialCurrencyBalanceAsync

`static GetOfficialCurrencyBalanceAsync() → OfficialCurrencyBalanceRequest`

该异步方法用于获取 ZEPETO 官方货币（ZEM）的余额。

**返回值：** `OfficialCurrencyBalanceRequest` — 一个 `OfficialCurrencyBalanceRequest` 对象。异步处理完成后，可通过 `responseData` 属性访问 `BalanceResponse` 对象。

## CurrencyError

`enum`

表示货币相关请求失败原因的错误代码。

| 名称           | 值  | 说明                          |
| ------------ | -- | --------------------------- |
| Unknown      | -1 | 错误：未知错误。                    |
| NetworkError | 0  | 错误：与网络问题相关的错误，包括连接中断或连接不稳定。 |