DEV Community

Roberto de Vargas Neto
Roberto de Vargas Neto

Posted on

Financial Custody: Managing Balance and Portfolio with Eventual Consistency

#springboot #java #microservices #kafka

Hey folks!

Continuing the My Broker B3 series, we've reached one of the most business-logic-rich services in the ecosystem: the Broker Wallet API.

In previous posts we built the B3 infrastructure (market price sync and matching engine). Now we enter the financial core of the broker. This service is the guardian of the investor's money and assets — it needs to be correct above all else.

🏦 What is the Wallet API?

The trading-broker-wallet is the financial custody service of the ecosystem. Its responsibility is to react to order lifecycle events and ensure the user's money and assets are managed correctly at each step.

It doesn't receive direct buy commands — it listens to Kafka events and acts according to each order's status:

Kafka: order-events-v1
         │
    ┌────┴────────────────────────┐
    │                             │
 PENDING                       FILLED / REJECTED
    │                             │
 reserveBalance()          settleOrder() / refundBalance()
    │                             │
 Blocks balance            Settles or refunds
Enter fullscreen mode Exit fullscreen mode

🎯 Why is the Wallet so Critical?

Imagine the following scenario without proper custody:

  1. User has R$ 1,000 available
  2. Places a buy order for R$ 800
  3. Before the order is processed, places another order for R$ 500
  4. Both orders are executed → user ends up with negative balance

The wallet solves this with the concept of blocked balance: the moment an order enters as PENDING, the value is immediately reserved. The available balance is always balance - blockedBalance.

🛠️ Tech Stack

Technology Usage
Java 21 + Spring Boot 3.5.11 Service core
MySQL + Flyway Operational persistence and versioning
Spring Kafka Order event consumption
Spring Data Redis Real-time prices for portfolio valuation
SpringDoc OpenAPI Swagger UI documentation

🏗️ The Data Model

Before diving into the logic, it's important to understand the three entities that support the service:

Account
├── userId (UNIQUE)
├── balance          ← total balance (includes blocked amount)
├── blockedBalance   ← amount reserved for PENDING orders
└── currency

Account (1) ──▶ (N) Position
                     ├── ticker
                     ├── quantity
                     └── averagePrice

WalletTransaction (audit log)
├── orderId
├── userId
├── transactionType  ← RESERVE | SETTLEMENT | REFUND
└── amount
Enter fullscreen mode Exit fullscreen mode

The blockedBalance is the central piece of custody. The balance never goes below zero — only blockedBalance goes up and down as orders progress through their lifecycle.

🔄 The Order Lifecycle in the Wallet

Step 1 — PENDING: Reserving the Balance

When an order is created, it arrives as PENDING. The wallet must immediately block the maximum amount that could be debited (quantity × limit price):

@Transactional
public void reserveBalance(OrderEventDTO event) {
    BigDecimal amountToReserve = event.getPrice().multiply(event.getQuantity());

    Account account = accountRepository.findByUserId(event.getUserId())
            .orElseThrow(() -> new RuntimeException("Account not found for user: " + event.getUserId()));

    // Available = balance - blockedBalance
    BigDecimal availableBalance = account.getAvailableBalance();

    if (availableBalance.compareTo(amountToReserve) < 0) {
        throw new RuntimeException("Insufficient balance to reserve funds.");
    }

    // Only blockedBalance increases — total balance stays intact
    account.setBlockedBalance(account.getBlockedBalance().add(amountToReserve));
    accountRepository.save(account);

    // Audit record
    walletTransactionRepository.save(WalletTransaction.builder()
            .userId(event.getUserId())
            .orderId(event.getOrderId())
            .transactionType(TransactionType.RESERVE)
            .amount(amountToReserve)
            .build());
}
Enter fullscreen mode Exit fullscreen mode

Important point: the total balance doesn't change at this step. Only blockedBalance increases. The money is still in the account — it's just reserved.

Step 2a — FILLED: Settling the Order

The order was executed by the Matching Engine. Now the money actually leaves. But here's a subtlety: the executed price may differ from the reserved price.

Example: user placed a buy order with a limit of R$ 30.00, but the market executed at R$ 29.50. The reserved amount was R$ 300 (10 shares × R$ 30), but the actual executed amount was R$ 295 (10 × R$ 29.50). The R$ 5.00 difference automatically becomes available again.

@Transactional
public void settleOrder(OrderEventDTO event) {
    BigDecimal totalReserved = event.getPrice().multiply(event.getQuantity());
    BigDecimal totalExecuted = event.getExecutedPrice().multiply(event.getQuantity());

    Account account = accountRepository.findByUserId(event.getUserId())
            .orElseThrow(() -> new RuntimeException("Account not found"));

    // Release the initial block
    BigDecimal newBlockedBalance = account.getBlockedBalance().subtract(totalReserved);
    account.setBlockedBalance(newBlockedBalance.compareTo(BigDecimal.ZERO) < 0
            ? BigDecimal.ZERO
            : newBlockedBalance);

    // Debit the actual executed amount from total balance
    account.setBalance(account.getBalance().subtract(totalExecuted));
    accountRepository.save(account);

    // Update asset position
    updatePosition(event, account);
}
Enter fullscreen mode Exit fullscreen mode

Step 2b — REJECTED: Refunding the Balance

The order was rejected (price outside market range, ticker not found in Redis, etc.). The blocked money becomes available again:

@Transactional
public void refundBalance(OrderEventDTO event) {
    BigDecimal amountToRefund = event.getPrice().multiply(event.getQuantity());

    Account account = accountRepository.findByUserId(event.getUserId())
            .orElseThrow(() -> new RuntimeException("Account not found for refund"));

    // Only subtract from blockedBalance — total balance was never touched
    if (account.getBlockedBalance().compareTo(amountToRefund) >= 0) {
        account.setBlockedBalance(account.getBlockedBalance().subtract(amountToRefund));
    } else {
        log.warn("Refund amount exceeds blocked balance for order {}", event.getOrderId());
        account.setBlockedBalance(BigDecimal.ZERO);
    }

    accountRepository.save(account);
}
Enter fullscreen mode Exit fullscreen mode

📊 Weighted Average Price Calculation

When a purchase is settled, we need to update the user's position in that asset. The weighted average price ensures that purchases made at different times are correctly reflected:

New Average Price = (Current Cost + New Cost) / (Current Qty + New Qty)
Enter fullscreen mode Exit fullscreen mode 
private void updatePosition(OrderEventDTO event, Account account) {
    Position position = positionRepository
            .findByAccountIdAndTicker(account.getId(), event.getTicker())
            .orElse(Position.builder()
                    .account(account)
                    .ticker(event.getTicker())
                    .quantity(BigDecimal.ZERO)
                    .averagePrice(BigDecimal.ZERO)
                    .build());

    boolean isSell = "SELL".equalsIgnoreCase(event.getSide());

    if (isSell) {
        BigDecimal newQuantity = position.getQuantity().subtract(event.getQuantity());
        if (newQuantity.compareTo(BigDecimal.ZERO) <= 0) {
            positionRepository.delete(position);
            return;
        }
        position.setQuantity(newQuantity);
        // Average price stays the same on sell
    } else {
        // BUY: recalculate weighted average price
        BigDecimal currentCost = position.getAveragePrice().multiply(position.getQuantity());
        BigDecimal newCost = event.getExecutedPrice().multiply(event.getQuantity());
        BigDecimal totalQuantity = position.getQuantity().add(event.getQuantity());
        BigDecimal newAveragePrice = currentCost.add(newCost)
                .divide(totalQuantity, 4, RoundingMode.HALF_UP);

        position.setQuantity(totalQuantity);
        position.setAveragePrice(newAveragePrice);
    }

    positionRepository.save(position);
}
Enter fullscreen mode Exit fullscreen mode

Practical example:

  • Purchase 1: 10 PETR4 shares at R$ 30.00 → average price = R$ 30.00
  • Purchase 2: 5 PETR4 shares at R$ 33.00 → average price = (300 + 165) / 15 = R$ 31.00

🐛 Critical Bugs Fixed

During the code review, I identified issues that would cause silent failures in production:

1. Guaranteed NPE on first deposit
New account created without initializing blockedBalance. The first call to getAvailableBalance() would throw NullPointerException.

// ❌ Before
Account.builder()
    .balance(BigDecimal.ZERO)
    // blockedBalance missing → NPE

// ✅ After
Account.builder()
    .balance(BigDecimal.ZERO)
    .blockedBalance(BigDecimal.ZERO)
Enter fullscreen mode Exit fullscreen mode

2. Withdraw validated total balance, not available balance
Allowed withdrawing money that was blocked in pending orders:

// ❌ Before — allows withdrawing reserved funds
if (account.getBalance().compareTo(amount) < 0)

// ✅ After — validates only what's available
if (account.getAvailableBalance().compareTo(amount) < 0)
Enter fullscreen mode Exit fullscreen mode

3. SELL increased position instead of decreasing it
The updatePosition() method always added quantity, completely ignoring the side field. Selling 10 shares would add 10 to the position.

4. Kafka consumer silently swallowed exceptions
Errors were logged but the offset was committed — the message was discarded without retry. Now the consumer rethrows the exception so Kafka can apply its retry policy correctly.

🔒 Idempotency

To prevent duplicates in case of Kafka reprocessing, we added a database constraint:

-- V4 migration
ALTER TABLE wallet_transactions
    ADD CONSTRAINT uq_order_transaction UNIQUE (order_id, transaction_type);
Enter fullscreen mode Exit fullscreen mode

If the same PENDING event arrives twice, the second insert will fail with a constraint violation — preventing the balance from being blocked twice for the same order.

🌐 REST API

Method Endpoint Description
POST /api/v1/wallet/{userId}/deposit Deposit funds
POST /api/v1/wallet/{userId}/withdraw Withdraw available funds
GET /api/v1/wallet/{userId}/summary Summary: balance + positions + total equity
GET /api/v1/wallet/{userId}/positions List asset positions
GET /api/v1/wallet/{userId}/transactions Transaction history

📄 Swagger UI: http://localhost:8085/swagger-ui.html

✅ Validating the Execution

With the application running locally:

  • ✅ Flyway applied all 4 migrations successfully
  • ✅ Hibernate validated the schema
  • ✅ Kafka consumer connected and subscribed to order-events-v1
  • ✅ Consumer group trading-broker-wallet synced
  • ✅ Swagger UI with 5 documented endpoints at http://localhost:8085/swagger-ui.html

🚀 What's Next?

With the Wallet ready to react to order events, the next step is building the trading-broker-order — the orchestrator that will manage the complete order lifecycle:

  1. Receive buy/sell intent via REST
  2. Validate the ticker against trading-broker-asset
  3. Save the order as PENDING and publish to Kafka
  4. Send the order to the Matching Engine via RabbitMQ
  5. Consume the result and update the final status

Once that service is ready, we'll have the first complete end-to-end flow: from the user's click all the way to the updated wallet balance.

Got any questions about the custody logic or the PENDING → FILLED → REJECTED cycle? Drop them in the comments!

🔎 About the Series

⬅️ Previous Post: The Heart of B3: Building the Matching Engine with RabbitMQ and Redis

📘 Series Index: Series Roadmap

Links:

Top comments (0)