Quick Tutorials

Building a Wallet Management System

Learn how to implement a complete wallet management system with LedgerForge.

This tutorial will guide you through implementing a simple wallet management system using the LedgerForge Ledger. By the end, you'll have built a system that can:

Create customer wallets.
Link wallets to customer identities.
Support deposits and withdrawals from wallets.
Create purpose-specific wallets (e.g. card balances).
Enable transfers between wallets.

For this tutorial, we'll use the LedgerForge TypeScript SDK and LedgerForge Go SDK for the implementation.

Designing your map

Before writing code, it's crucial to design a money movement map that outlines how money moves in your system. This serves as the blueprint for your implementation.

For our wallet management system, here's how funds will flow:

Ledger Map Topology Design

@World

External bank pool

⇄

Main Wallet

User deposit account

➔

Card Wallet

Virtual card balance

Tip

Three core nodes in this map:

@World: Represents external funding sources and withdrawal destinations.
Main Wallet: The customer's primary wallet for deposits and withdrawals.
Card Wallet: A secondary wallet dedicated purely to card-related transactions.

Set up your implementation

Based on our map, we'll implement the following steps:

Create a customer ledger to organise all customer wallets.
Create customer identity for storing user information.
Create a main wallet and link it to the identity.
Implement deposit functionality.
Implement withdrawal functionality.
Create a card wallet and link it to the same identity.
Fund the card wallet from the main wallet.

Create customer ledger

Tip

You can also create separate ledgers for different wallet types to keep your balances structured.

curl --request POST \
  --url http://localhost:5001/ledgers \
  --header 'X-ledgerforge-key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Customer Wallets Ledger",
    "meta_data": {
        "description": "Ledger for managing customer wallets",
        "application": "Wallet Management System"
    }
  }'

Warning

Always save the ledger_idin your database. You'll use this ID to create balances for the customer wallets.

Create customer identity

Create a customer identity to store user profile information:

async function createCustomerIdentity(customerData) {
  const ledgerforge = await getLedgerForgeInstance();
  const { Identities } = ledgerforge;
  
  const identity = await Identities.create({
    identity_type: "individual",
    first_name: customerData.firstName,
    last_name: customerData.lastName,
    email_address: customerData.email,
    phone_number: customerData.phone,
    meta_data: {
      customer_id: customerData.customerId,
      registration_date: new Date().toISOString()
    }
  });
  
  return identity.data.identity_id;
}

Create main wallet

Create a balance to represent the customer main wallet and link to the customer identity:

curl --request POST \
  --url http://localhost:5001/balances \
  --header 'X-ledgerforge-key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "ledger_id": "<customer-wallets-ledger-id>",
    "identity_id": "<customer-identity-id>",
    "currency": "USD",
    "meta_data": {
        "wallet_type": "main",
        "purpose": "general",
        "status": "active"
    }
  }'

Success

Successfully completed wallet setup logic. You can now support deposits, internal transfers and virtual card allocations!