Getting Started

Getting Started with LedgerForge Core

The developer-first toolkit for building compliant financial products.

This is your guide to getting started with LedgerForge, pronounced as /blank/.

If you are new to LedgerForge or open-source fintech developer tools, this is where you should start.

Need help with your product?

Get dedicated support for architecture reviews, integration planning, ledger workflows, and production deployment.

Speak with us

1: Installation Guide

Manually install LedgerForge 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 LedgerForge repository into your machine:

bash

git clone https://github.com/ledgerforgefinance/ledgerforge && cd ledgerforge

Create configuration file

Create a configuration file, ledgerforge.json:

bash

touch ledgerforge.json

Configure LedgerForge

Copy and save the following configuration:

json

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

Start LedgerForge server

Start your LedgerForge server with Docker compose:

bash

docker compose up

Success

Your LedgerForge 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 LedgerForge is running, let's create your first transaction. LedgerForge 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-ledgerforge-key: <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 1000,
    "reference": "first_transaction_001",
    "currency": "USD",
    "precision": 100,
    "source": "@FundingPool",
    "destination": "@MyBalance",
    "description": "My first LedgerForge transaction",
    "allow_overdraft": true,
    "meta_data": {}
  }'

Response payload:

json

{
  "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 LedgerForge transaction",
  "allow_overdraft": true,
  "status": "QUEUED",
  "created_at": "2024-12-21T01:36:46.997063436Z",
  "meta_data": {}
}

Success

Congratulations! You've successfully created your first transaction in LedgerForge.

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

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

json

{
  "balances": [
    {
      "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,
      "precision": 100,
      "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,
      "precision": 100,
      "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
    }
  ]
}

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 LedgerForge Cloud dashboard.

Tip

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

Key concepts

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

Ledgers

Organize ledgers for your application and segment your financial accounts.

Balances

Wallets, internal stores of value, credit segments, and customer asset pools.

Transactions

Record, batch, route, and move money safely between ledger balances.

Identities

Link people, merchants, and institutions legally to ledger balances.