Skip to main content
This tutorial will guide you through implementing a simple wallet management system using the Blnk Ledger. By the end, you’ll have built a system that can:
  1. Create customer wallets.
  2. Link wallets to customer identities.
  3. Support deposits and withdrawals from wallets.
  4. Create purpose-specific wallets (e.g. card balances).
  5. Enable transfers between wallets.
For this tutorial, we’ll use the Blnk TypeScript SDK and Blnk Go SDK for the implementation. If you prefer, you can also refer to the API reference for details on the available endpoints.

​
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: Wallet management map Explore the map yourself here This map shows three key components:
  • @World: Represents external funding sources and withdrawal destinations.
  • Main Wallet: The customer’s primary wallet for deposits and withdrawals.
  • Card Wallet: A second wallet for card-related transactions.
From our map, we can verify that:
  • Customers can deposit money from external sources to their main wallet.
  • Customers can withdraw money from their main wallet to external destinations.
  • Customers can transfer money from their main wallet to their card wallet.

​
Set up your implementation

Based on our map, we’ll implement the following steps:
  1. Create a customer ledger to organise all customer wallets.
  2. Create customer identity for storing user information.
  3. Create a main wallet and link it to the identity.
  4. Implement deposit functionality.
  5. Implement withdrawal functionality.
  6. Create a card wallet and link it to the same identity.
  7. Fund the card wallet from the main wallet.

​
Prerequisites

Before starting, ensure you have:
  1. A running Blnk Core instance (e.g. at http://localhost:5001).
  2. An API key for Blnk (replace YOUR_API_KEY in the code examples). Required for authenticated requests.
  3. Optionally, you can connect your Blnk Core to your Blnk Cloud workspace to view your ledger data.

​
Initialise your client

Initialize the Blnk client once at the start of your application: 
const { BlnkInit } = require('@blnkfinance/blnk-typescript');

let blnkInstance = null;

async function getBlnkInstance() {
  if (!blnkInstance) {
    blnkInstance = await BlnkInit('', { baseUrl: 'http://localhost:5001' });
  }
  return blnkInstance;
}

​
Create customer ledger

You can also create separate ledgers for different wallet types, e.g., Customer Main Ledger and Customer Card Ledger, to keep your balances more organized.
Create a ledger to organize all customer wallets — main and card wallets: 
curl --request POST \
  --url http://localhost:5001/ledgers \
  --header 'X-blnk-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"
    }
  }'
Always save the ledger_id in 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: 
curl --request POST \
  --url http://localhost:5001/identities \
  --header 'X-blnk-key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "identity_type": "individual",
    "first_name": "Alice",
    "last_name": "Johnson",
    "email_address": "alice@example.com",
    "phone_number": "+1234567890",
    "meta_data": {
        "customer_id": "CUST-001",
        "registration_date": "2024-02-25T10:30:00Z"
    }
  }'
Always save the identity_id in your database. You’ll use this ID to link balances to this identity or query all balances owned by this identity.

​
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-blnk-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"
    }
  }'
Always store the balance_id in your database and associate it with the customer. You’ll use this ID for all future transactions involving this wallet.

​
Funding the main wallet

Use an internal balance to represent external deposit sources—such as bank accounts, cards, and other funding methods—responsible for funding a customer’s wallet. Record a deposit from an external source to fund the main wallet: 
curl --request POST \
  --url http://localhost:5001/transactions \
  --header 'X-blnk-key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 1000,
    "precision": 100,
    "reference": "DEP-20250225-103000",
    "description": "Initial deposit",
    "currency": "USD",
    "source": "@WorldUSD",
    "destination": "<customer-main-balance-id>",
    "allow_overdraft": true,
    "meta_data": {
        "transaction_type": "deposit",
        "channel": "bank_transfer"
    }
  }'
Setting allow_overdraft to true enables the transaction to proceed even if the source balance lacks sufficient funds.

​
Withdrawals from the main wallet

You can use the same internal balance to represent external withdrawal destinations to balance out your ledger, or you can allocate a separate internal balance specifically for withdrawals. Record a withdrawal from the main wallet to an external destination: 
curl --request POST \
  --url http://localhost:5001/transactions \
  --header 'X-blnk-key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 100,
    "precision": 100,
    "reference": "WDR-20250225-104500",
    "description": "Wallet withdrawal",
    "currency": "USD",
    "source": "<customer-main-balance-id>",
    "destination": "@WorldUSD",
    "meta_data": {
        "transaction_type": "withdrawal",
        "channel": "atm"
    }
  }'

​
Creating a card balance

To create a card balance and link it to the customer: 
curl --request POST \
  --url http://localhost:5001/balances \
  --header 'X-blnk-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": "card",
        "purpose": "card_payments",
        "status": "active",
        "card_details": {
            "masked_number": "xxxx-xxxx-xxxx-1234",
            "expiry": "12/25",
            "type": "virtual"
        }
    }
  }'

​
Funding the card from main wallet

Record a transaction between both balances to fund your card balance: 
curl --request POST \
  --url http://localhost:5001/transactions \
  --header 'X-blnk-key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 200,
    "precision": 100,
    "reference": "TRF-20250225-110000",
    "description": "Transfer to card wallet",
    "currency": "USD",
    "source": "<customer-main-balance-id>",
    "destination": "<customer-card-balance-id>",
    "meta_data": {
        "transaction_type": "internal_transfer",
        "purpose": "fund_card"
    }
  }'

​
Conclusion

You should now have a fully functional and scalable wallet management system. As your application grows, you can expand its capabilities with features like transaction history, scheduled transfers, balance monitors, and notifications to enhance performance and user experience.