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

# Wallets

> Managing financial accounts in Zeus

## Overview

A **Wallet** represents a financial account where you track money. This could be:

* Cash in your pocket
* Bank checking account
* Savings account
* Credit card (with negative balance)
* Investment account

## Wallet Properties

| Property     | Type       | Description                                   |
| ------------ | ---------- | --------------------------------------------- |
| `id`         | String     | Local UUID (primary key)                      |
| `serverId`   | String?    | Server-assigned ID after sync                 |
| `name`       | String     | Display name (e.g., "Cash", "Chase Checking") |
| `currency`   | String     | ISO 4217 currency code (e.g., "USD", "EUR")   |
| `balance`    | double     | Current balance                               |
| `syncStatus` | SyncStatus | Current sync state                            |

## Creating a Wallet

### Using the Cache Manager

```dart theme={null}
final cache = CacheManager.instance;

final wallet = await cache.createWallet(
  name: 'Cash',
  currency: 'USD',
  initialBalance: 100.0,
);

print('Created wallet: ${wallet.id}');
```

### Direct Repository Access

```dart theme={null}
final wallet = Wallet(
  id: cache.generateId(),
  name: 'Chase Checking',
  currency: 'USD',
  balance: 1500.00,
  createdAt: DateTime.now(),
  updatedAt: DateTime.now(),
);

await cache.wallets.save(wallet);
```

## Querying Wallets

### Get All Wallets

```dart theme={null}
final wallets = await cache.wallets.findAll();
```

### Find by ID

```dart theme={null}
final wallet = await cache.wallets.findById('wallet-uuid');
if (wallet != null) {
  print('Balance: ${wallet.balance}');
}
```

### Get Pending Sync

```dart theme={null}
final pending = await cache.wallets.findPendingSync();
```

## Updating Wallets

```dart theme={null}
final wallet = await cache.wallets.findById(walletId);
if (wallet != null) {
  final updated = wallet.copyWith(
    name: 'Updated Name',
    balance: wallet.balance + 50.0,
  );
  await cache.wallets.save(updated);
}
```

<Note>
  When you save an existing wallet, its `syncStatus` automatically changes to `pendingUpdate` (if it was `synced`).
</Note>

## Deleting Wallets

### Soft Delete (Default)

Soft delete marks the wallet as deleted but keeps it locally until sync completes:

```dart theme={null}
await cache.wallets.delete(walletId);
```

The wallet will:

1. Be marked with `isDeleted = true`
2. Get `syncStatus = pendingDelete`
3. Not appear in `findAll()` results
4. Sync to server
5. Be hard-deleted after successful sync

### Hard Delete

Hard delete removes the wallet immediately (use with caution):

```dart theme={null}
await cache.wallets.delete(walletId, hardDelete: true);
```

<Warning>
  Hard-deleted wallets cannot be recovered and will not sync to the server.
</Warning>

## Currency Support

Zeus uses ISO 4217 currency codes. Common codes:

| Code | Currency        |
| ---- | --------------- |
| USD  | US Dollar       |
| EUR  | Euro            |
| GBP  | British Pound   |
| JPY  | Japanese Yen    |
| CAD  | Canadian Dollar |

## Best Practices

1. **Use descriptive names** - "Chase Checking" is better than "Bank"
2. **Set initial balance** - Track your starting point
3. **One wallet per account** - Don't mix different accounts
4. **Regular reconciliation** - Compare with bank statements

## Related

* [Categories](/concepts/categories) - Organize transactions
* [Transactions](/concepts/transactions) - Record wallet activity
* [Sync](/concepts/sync) - How wallets sync across devices