Blnk Developer Documentation • Open-source Backend for Financial Products

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.

1: Installation Guide

Self-hosted
Managed hosting

Manually install Blnk on your own infrastructure. This option requires Docker and Docker Compose.

Install prerequisites

Make sure you have Docker and Compose installed and running on your machine.

Clone the repository

Clone the Blnk repository into your machine:

bash

git clone https://github.com/blnkfinance/blnk && cd blnk

Create configuration file

Create a configuration file, blnk.json:

bash

touch blnk.json

Configure Blnk

Copy and save the following configuration:

blnk.json

{
  "project_name": "Blnk",
  "data_source": {
    "dns": "postgres://postgres:password@postgres:5432/blnk?sslmode=disable"
  },
  "redis": {
    "dns": "redis:6379"
  },
  "typesense": {
    "dns": "http://typesense:8108"
  },
  "server": {
    "port": "5001"
  }
}

Start Blnk server

Start your Blnk server with Docker compose:

bash

docker compose up

Your Blnk server is now running! You can verify it’s working by visiting http://localhost:5001 in your browser.

2: Create your first transaction

Now that Blnk is running, let’s create your first transaction. Blnk uses the double entry principle to record transactions, which means every transaction must have a source and destination.

curl -X POST 'http://localhost:5001/transactions' \
  -H 'X-blnk-key: <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "precise_amount": 100000,
    "reference": "first_transaction_001",
    "currency": "USD",
    "precision": 100,
    "source": "@FundingPool",
    "destination": "@MyBalance",
    "description": "My first Blnk transaction",
    "allow_overdraft": true,
    "meta_data": {}
  }'

const response = await blnk.Transactions.create({
  precise_amount: 100000,
  reference: 'first_transaction_001',
  currency: 'USD',
  precision: 100,
  source: '@FundingPool',
  destination: '@MyBalance',
  description: 'My first Blnk transaction',
  allow_overdraft: true,
  meta_data: {},
});

transaction, resp, err := client.Transaction.Create(blnkgo.CreateTransactionRequest{
  ParentTransaction: blnkgo.ParentTransaction{
    PreciseAmount: big.NewInt(100000),
    Reference:   "first_transaction_001",
    Currency:    "USD",
    Precision:   100,
    Source:      "@FundingPool",
    Destination: "@MyBalance",
    Description: "My first Blnk transaction",
  },
  AllowOverdraft: true,
})

response = blnk.transactions.create({
  "precise_amount": 100000,
  "reference": "first_transaction_001",
  "currency": "USD",
  "precision": 100,
  "source": "@FundingPool",
  "destination": "@MyBalance",
  "description": "My first Blnk transaction",
  "allow_overdraft": True,
  "meta_data": {},
})

Response

{
  "id": "txn_6164573b-6cc8-45a4-ad2e-7b4ba6a60f7d",
  "source": "@FundingPool",
  "destination": "@MyBalance",
  "reference": "first_transaction_001",
  "amount": 1000,
  "precision": 100,
  "precise_amount": 100000,
  "currency": "USD",
  "description": "My first Blnk transaction",
  "allow_overdraft": true,
  "status": "QUEUED",
  "created_at": "2024-12-21T01:36:46.997063436Z",
  "meta_data": {}
}

Congratulations! You’ve successfully created your first transaction in Blnk.

Finally, let’s view our balances to confirm that the transaction was recorded:

curl -X GET 'http://localhost:5001/balances' \
  -H 'X-blnk-key: <api-key>'

Response

[
  {
    "balance": -1000,
    "version": 1,
    "inflight_balance": 0,
    "credit_balance": 0,
    "inflight_credit_balance": 0,
    "debit_balance": 1000,
    "inflight_debit_balance": 0,
    "queued_credit_balance": 0,
    "queued_debit_balance": 0,
    "ledger_id": "ldg_073f7ffe-9dfd-42ce-aa50-d1dca1788adc",
    "identity_id": "",
    "balance_id": "bln_ebcd230f-6265-4d4a-a4ca-45974c47f746",
    "indicator": "@FundingPool",
    "currency": "USD",
    "created_at": "2024-12-21T01:36:46.997063436Z",
    "meta_data": null
  },
  {
    "balance": 1000,
    "version": 1,
    "inflight_balance": 0,
    "credit_balance": 1000,
    "inflight_credit_balance": 0,
    "debit_balance": 0,
    "inflight_debit_balance": 0,
    "queued_credit_balance": 0,
    "queued_debit_balance": 0,
    "ledger_id": "ldg_073f7ffe-9dfd-42ce-aa50-d1dca1788adc",
    "identity_id": "",
    "balance_id": "bln_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "indicator": "@MyBalance",
    "currency": "USD",
    "created_at": "2024-12-21T01:36:46.997063436Z",
    "meta_data": null
  }
]

Balance fields are integers in minor units. Blnk Core does not return precision on balance responses. Use the same precision you pass on transactions for each currency (for example, 100 for USD) to convert integers to display amounts: display_amount = balance / precision.

This will return a list of all balances in your system. You should see the @FundingPool balance (which will be negative since it funded the transaction) and the @MyBalance balance (which will show the amount we transferred).

3: View your ledger (optional)

See your new balances and transaction in your Blnk Cloud dashboard.

To learn more about navigating your ledger, see our Blnk Cloud guide.

You’ve successfully completed the Blnk getting started guide! You now have a working Blnk instance with your first transaction recorded.

Key concepts

Now that you’re set up, start with these key concepts to build your application:

Ledgers

Organize ledgers for your application.

Balances

Wallets, accounts, and stores of value.

Transactions

Record and move money between balances.

Identities

Link people and entities to balances.

Using TypeScript? See the TypeScript SDK quick start. Using Go? See the Go SDK quick start.

Start Here

Ledgers

Ledger balances

Transactions

Reconciliation

Identities

Metadata

Search

Webhooks

API keys

Guides

Configuration

Advanced

Migration guides

Getting Started with Blnk Core

1: Installation Guide

Install prerequisites

Clone the repository

Create configuration file

Configure Blnk

Start Blnk server

Create an instance on Cloud

Provide instance details

Verify connection

2: Create your first transaction

3: View your ledger (optional)

Key concepts

Ledgers

Balances

Transactions

Identities

​1: Installation Guide

Install prerequisites

Clone the repository

Create configuration file

Configure Blnk

Start Blnk server

Sign up to Blnk Cloud

Create an instance on Cloud

Provide instance details

Verify connection

​2: Create your first transaction

​3: View your ledger (optional)

​Key concepts

Ledgers

Balances

Transactions

Identities

1: Installation Guide

2: Create your first transaction

3: View your ledger (optional)

Key concepts