​
Overview

This is your guide to getting started with Blnk, pronounced as /blank/. If you are new to Blnk or open-source fintech developer tools, this is where you should start.
Here is your start kit: ✨

1. Install Blnk

2. Launch Blnk

3. Create your first ledger

4. Create your first balance

5. Record your first transaction

6. Run your first reconciliation

​
What is Blnk?

Blnk offers an open-source financial ledger database for building and scaling fintech products. With Blnk, you can:
  • Accurately record transactions in your system.
  • Correctly manage complex flow of funds and transaction data.
  • Reliably manage the size of your transactions as your product scales.

​
1. Install Blnk on your machine

To install Blnk, make sure you have Docker and Compose installed and running on your machine. To get started with Blnk, first clone the repository into your machine:
bash
git clone https://github.com/blnkfinance/blnk && cd blnk
Next, create a configuration file, blnk.json:
bash
touch blnk.json
Then copy and save the following configuration:
Remember to change your password before deploying to production.
blnk.json
{
  "project_name": "Blnk",
  "data_source": {
    "dns": "postgres://postgres:password@postgres:5432/blnk?sslmode=disable"
  },
  "redis": {
    "dns": "redis:6379"
  },
  "server": {
    "port": "5001"
  },
  "queue": {
    "monitoring_port": "5004"
  }
}

Advanced Blnk configuration

Learn how to set up advanced configuration for your Blnk server.

​
2. Launch Blnk

Start your Blnk server with Docker compose:
bash
docker compose up
If successful, you should be able to access your server on the following URL: 
http://localhost:5001

​
3. Create your first ledger

Everything in Blnk begins with a ledger. Ledgers are used to group and manage how you arrange your ledger balances in our application. When you install Blnk, an internal ledger called the General Ledger is created for you. This is a ledger meant for grouping all of the balances directly owned by your organization, e.g., Revenue, Fees, etc. However, to create, store and represent balances for accounts/wallets owned by the users in your application, it is required to create ledgers to group them in. To create a ledger, call the create-ledger endpoint: 
POST http://YOUR_BLNK_INSTANCE_URL/ledgers
With the following request body: 
{
    "name": "Customer Savings Account",
    "meta_data": {
        "project_owner": "YOUR_APP_NAME"
    }
}
Response
{
    "ledger_id": "ldg_073f7ffe-9dfd-42ce-aa50-d1dca1788adc",
    "name": "Customer Savings Account",
    "created_at": "2024-12-21T01:36:46.997063436Z",
    "meta_data":{
        "project_owner": "YOUR_APP_NAME"
    }
}
FieldDescriptionRequiredType
nameA name that best describes the function of the ledgerYesstring
meta_dataCustom data associated with the ledger being createdNoobject
Next, you can view a list of all your ledgers:
Blnk CLI
blnk ledgers list

​
4. Create your first balance

Ledger balances (or balances for short) are used to represent store of value in a fintech application, e.g., wallet, crypto, account, card balance, etc. They represent the source or destination of a transaction record. To create a balance, call the create-balance endpoint: 
POST http://YOUR_BLNK_INSTANCE_URL/balances
With the following request body: 
{
    "ledger_id": "ldg_073f7ffe-9dfd-42ce-aa50-d1dca1788adc",
    "currency": "USD",
    "meta_data": {
        "first_name": "Alice",
        "last_name": "Hart",
        "account_number": "1234567890"
    }
}
Response
{
    "balance_id": "bln_0be360ca-86fe-457d-be43-daa3f966d8f0",
    "balance": 0,
    "version": 0,
    "inflight_balance": 0,
    "credit_balance": 0,
    "inflight_credit_balance": 0,
    "debit_balance": 0,
    "inflight_debit_balance": 0,
    "precision": 0,
    "ledger_id": "ldg_073f7ffe-9dfd-42ce-aa50-d1dca1788adc",
    "identity_id": "",
    "indicator": "",
    "currency": "USD",
    "created_at": "2024-02-20T05:33:01.311600208Z",
    "meta_data": {
        "first_name": "Alice",
        "last_name": "Hart",
        "account_number": "1234567890"
    }
}
FieldDescriptionRequiredType
ledger_idThe unique id of the ledger that this balance belongs to.Yesstring
currencyThe currency in which transactions recorded in this balance will be recorded.Yesstring
meta_dataCustom data associated with the balance being createdNoobject
Next, to view a list of all your balances:
bash
blnk balances list

​
5. Record your first transaction

Transactions represent all financial activities happening in your application. Blnk uses the double entry principle to record transactions, i.e., to successfully record a transaction, there must be a source and a destination. In the code example below, we’ll fund our balance created above with a starting amount. To record a transaction, call the record-transaction endpoint: 
POST http://YOUR_BLNK_INSTANCE_URL/transactions
With the following request body: 
{
    "amount": 750,
    "reference": "ref_001adcfgf",
    "currency": "USD",
    "precision": 100,
    "source": "@FundingPool",
    "destination": "bln_ebcd230f-6265-4d4a-a4ca-45974c47f746",
    "description": "Fund with starting balance amount",
    "allow_overdraft": true,
    "meta_data": {
      "sender_name": "John Doe",
      "sender_account": "00000000000"
    }
}
If this is your first transaction, the participating balances will start at 0. To ensure the transaction is successful, enable overdrafts as shown above, allowing the source balance to go negative.Learn more about Overdrafts and Negative Balances.
Response
{
    "id": "txn_6164573b-6cc8-45a4-ad2e-7b4ba6a60f7d",
    "source": "@FundingPool",
    "destination": "bln_ebcd230f-6265-4d4a-a4ca-45974c47f746",
    "reference": "ref_001adcfgf",
    "amount": 750,
    "precision": 100,
    "precise_amount": 75000,
    "currency": "USD",
    "description": "Fund with starting balance amount",
    "allow_overdraft": true,
    "status": "QUEUED",
    "created_at": "2024-12-21T01:36:46.997063436Z",
    "meta_data": {
      "sender_name": "John Doe",
      "sender_account": "00000000000"
    }
}
FieldDescriptionRequiredType
amountThe transaction amount.Yesfloat
referenceYour unique transaction reference to ensure idempotency.Yesstring
currencyShort code for your asset class. See also: Asset classesYesstring
precisionPrecision for the currency/asset passed. See also: PrecisionNoint64
sourceSender’s balance IDYesstring
destinationRecipient’s balance ID.Yesstring
descriptionDescription or narration of the transaction.Nostring
meta_dataCustom data associated with the transactionNoobject
Passing detailed data with the meta_data object is encouraged; it provides you with 360-degree insights about each transaction record. Examples of data you can pass include sender_name, account_number, bank_name, receiver_name, payment_id, ip_address, location, payment_method, etc.
Next, you can view a list of all transactions in your ledger:
bash
blnk transactions list

​
Use cases

Here’s some of what you can build with Blnk:

Crypto order exchange

Virtual card issuance

Savings application

Escrow application

​
Need help?

We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool. To ask questions or discuss issues, please contact us or join our Discord community.