Wallets

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

final cache = CacheManager.instance;

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

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

Direct Repository Access

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

final wallets = await cache.wallets.findAll();

Find by ID

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

Get Pending Sync

final pending = await cache.wallets.findPendingSync();

Updating Wallets

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);
}

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

Deleting Wallets

Soft Delete (Default)

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

await cache.wallets.delete(walletId);

The wallet will:

Be marked with isDeleted = true
Get syncStatus = pendingDelete
Not appear in findAll() results
Sync to server
Be hard-deleted after successful sync

Hard Delete

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

await cache.wallets.delete(walletId, hardDelete: true);

Hard-deleted wallets cannot be recovered and will not sync to the server.

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

Use descriptive names - “Chase Checking” is better than “Bank”
Set initial balance - Track your starting point
One wallet per account - Don’t mix different accounts
Regular reconciliation - Compare with bank statements

Categories - Organize transactions
Transactions - Record wallet activity
Sync - How wallets sync across devices

Introduction

Core Concepts

Overview

Wallet Properties

Creating a Wallet

Using the Cache Manager

Direct Repository Access

Querying Wallets

Get All Wallets

Find by ID

Get Pending Sync

Updating Wallets

Deleting Wallets

Soft Delete (Default)

Hard Delete

Currency Support

Best Practices

​Overview

​Wallet Properties

​Creating a Wallet

​Using the Cache Manager

​Direct Repository Access

​Querying Wallets

​Get All Wallets

​Find by ID

​Get Pending Sync

​Updating Wallets

​Deleting Wallets

​Soft Delete (Default)

​Hard Delete

​Currency Support

​Best Practices

​Related

Overview

Wallet Properties

Creating a Wallet

Using the Cache Manager

Direct Repository Access

Querying Wallets

Get All Wallets

Find by ID

Get Pending Sync

Updating Wallets

Deleting Wallets

Soft Delete (Default)

Hard Delete

Currency Support

Best Practices

Related