---
title: ZEPETO.Currency
slug: world-sdk-guide-kr/zepetocurrency
docTags: 
createdAt: 2026-09-04T05:54:31.424Z
---

| 형식                                            | 설명                                                                                                                   |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| [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  | 오류: 연결 끊김이나 불안정한 연결 등 네트워크 문제와 관련된 오류입니다. |