> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 获取消费账户

创建消费账户后，您可以通过以下查询访问它：

1. `getUserCashBalances` - 检索您所有消费账户的列表。
2. `getUserCashBalanceById` - 根据其 id 值检索特定的消费账户。

<Warning>
  **需要授权**

  此变更需要 `LIST_PAYMENT` 范围。请确保您的访问令牌已被授予此范围，然后再尝试内部转账。
</Warning>

## 消费账户详情

`UserCashBalanceDetails` 对象将包含有关消费账户的重要信息。

| 字段名                  | 类型                     | 描述                      |
| :------------------- | :--------------------- | :---------------------- |
| userCashBalanceId    | UUID!                  | 现金余额账户的唯一标识符            |
| totalCashBalance     | String!                | 账户中的总现金余额（从 0 开始）       |
| availableCashBalance | String!                | 可立即使用的可用现金余额（从 0 开始）    |
| lifetimeCashBalance  | String!                | 有史以来所有存入资金的累计总额（从 0 开始） |
| nickname             | String                 | 分配给该账户的自定义名称            |
| status               | UserCashBalanceStatus! | 账户当前状态（ACTIVE, CLOSED）  |
| isDefault            | Boolean!               | 消费账户是否为默认账户             |
| createdAt            | DateTime!              | 账户创建的时间戳                |
| updatedAt            | DateTime!              | 账户更新的时间戳                |

## 获取消费账户列表

要获取在您账户下创建的消费账户列表，请使用 `getUserCashBalances` 查询。该调用返回包含基本详情的消费账户列表，包括 `userCashBalanceId`。您将需要此 ID 通过 `getuserCashBalanceById` 检索特定的消费账户。

### 变量

| 字段       | 类型                         | 必填 | 描述                          |
| -------- | -------------------------- | -- | --------------------------- |
| filter   | UserCashBalanceFilterInput | 否  | 消费账户的筛选条件                   |
| paginate | OffsetInput                | 否  | 分页参数（默认：limit=20, offset=0） |

### 示例请求

```graphql theme={null}
query GetUserCashBalances(
  $filter: UserCashBalanceFilterInput,
  $paginate: OffsetInput,
) {
  getUserCashBalances(
    filter: $filter
    paginate: $paginate
  ) {
    userCashBalances {
        userCashBalanceId
        totalCashBalance
        availableCashBalance
        lifetimeCashBalance
        nickname
        status
        isDefault
        createdAt
        updatedAt
    }
    totalCount
    hasNextPage
  }
}
```

<Note>
  请注意，由于速率限制，您可能需要进行分页，并多次调用消费账户列表。
</Note>

### 示例响应

响应将包含一个消费账户列表

```json JSON theme={null}
{
    "data": {
        "getUserCashBalances": {
            "userCashBalances": [
                {
                    "userCashBalanceId": "c115604e-5d47-473c-a955-41a820cdcaf8",
                    "totalCashBalance": "0.00",
                    "availableCashBalance": "0.00",
                    "lifetimeCashBalance": "768.00",
                    "nickname": "Virtual Prepaid Account",
                    "status": "ACTIVE",
                    "isDefault": false,
                    "createdAt": "2025-10-10T15:30:02.535Z",
                    "updatedAt": "2026-04-22T16:07:18.618Z"
                },
                {
                    "userCashBalanceId": "1c1b5fcc-eb21-44c5-b678-9c41f3fa21b4",
                    "totalCashBalance": "36.00",
                    "availableCashBalance": "36.00",
                    "lifetimeCashBalance": "177.00",
                    "nickname": "austin1",
                    "status": "ACTIVE",
                    "isDefault": false,
                    "createdAt": "2026-02-27T22:18:28.814Z",
                    "updatedAt": "2026-04-22T15:43:52.031Z"
                },
                {
                    "userCashBalanceId": "6d1b4b19-deef-42f5-80d7-ec34804ce090",
                    "totalCashBalance": "425108.80",
                    "availableCashBalance": "425108.80",
                    "lifetimeCashBalance": "444096.44",
                    "nickname": "Main account",
                    "status": "ACTIVE",
                    "isDefault": true,
                    "createdAt": "2025-08-01T19:25:54.392Z",
                    "updatedAt": "2026-04-21T19:19:22.777Z"
                }
            ],
            "totalCount": 3,
            "hasNextPage": false
        }
    }
}
```

### 筛选选项

| 字段                | 类型                        | 描述             |
| :---------------- | :------------------------ | :------------- |
| userCashBalanceId | \[UUID!]                  | 按特定消费账户 ID 筛选  |
| nickname          | \[String!]                | 按消费账户昵称筛选      |
| status            | \[UserCashBalanceStatus!] | 按消费账户状态筛选      |
| isDefault         | Boolean                   | 按是否为默认消费账户筛选   |
| createdGte        | DateTime                  | 按创建日期筛选（大于或等于） |
| createdLte        | DateTime                  | 按创建日期筛选（小于或等于） |
| updatedGte        | DateTime                  | 按更新日期筛选（大于或等于） |
| updatedLte        | DateTime                  | 按更新日期筛选（小于或等于） |

**示例 - 仅获取 `ACTIVE` 消费账户**

```json theme={null}
{
	"filter": {
  	"status": [ACTIVE]
  }
}
```

### 分页

| 字段     | 类型  | 默认 | 最大值 | 描述        |
| ------ | --- | -- | --- | --------- |
| limit  | Int | 20 | 20  | 每页返回的交易数量 |
| offset | Int | 0  | -   | 要跳过的交易数量  |

**示例 - 第 1 页**:

```json theme={null}
{
	"paginate": {
  	"limit": 20,
  	"offset": 0
  }
}
```

**示例 - 第 2 页**:

```json theme={null}
{
	"paginate": {
  	"limit": 20,
  	"offset": 20,
	}
}
```

## 获取特定消费账户

要获取在您账户下创建的特定消费账户，请使用 `getUserCashBalanceById` 查询。该调用返回此消费账户的详细信息，包括 `userCashBalanceId` 及其余额。

### 变量

| 字段                | 类型      | 必填 | 描述       |
| ----------------- | ------- | -- | -------- |
| userCashBalanceId | String! | 是  | 消费账户的 ID |

### 示例请求

```graphql theme={null}
query GetUserCashBalanceById(
  $userCashBalanceId: String
) {
  getUserCashBalanceById(
    userCashBalanceId: $userCashBalanceId
  ) {
    userCashBalanceId
    totalCashBalance
    availableCashBalance
    lifetimeCashBalance
    nickname
    status
    isDefault
    createdAt
    updatedAt
  }
}
```

### 示例响应

响应将包含特定消费账户的详细信息

```json JSON theme={null}
{
    "data": {
        "getUserCashBalanceById": {
            "userCashBalanceId": "6d1b4b19-deef-42f5-80d7-ec34804ce090",
            "totalCashBalance": "425108.80",
            "availableCashBalance": "425108.80",
            "lifetimeCashBalance": "444096.44",
            "nickname": "Main account",
            "status": "ACTIVE",
            "isDefault": true,
            "createdAt": "2025-08-01T19:25:54.392Z",
            "updatedAt": "2026-04-21T19:19:22.777Z"
        }
    }
}
```

<br />