Here's the truth.

There's no single correct way to work with an open-source ledger like Blnk. It's intentionally flexible, so developers can adapt it to different workflows and requirements.

But to get the most out of Blnk, you need to understand how it works and develop new ways of modelling money movement for your app.

This guide works through the core techniques and mental models for working with Blnk. Whether it's a simple weekend project or production system serving millions of users, you'll learn best practices for deploying and operating Blnk with confidence.

The double-entry model

At the core of Blnk is double-entry accounting. Every movement of value is recorded as having a source and destination.

Best practice: model money as flows, not mutable balances.

Instead of updating balances directly, always ask:

• Where is it coming from?
• Where is it going for?

Balances are derived from transactions guaranteeing consistency, auditability, and safety under retries or concurrency. Blnk refuses any transactions that misses a source or destination.

Start with your ledger design

Most developers start with the user features and then work backwards into ledger design. Blnk works best when you flip the script.

Before writing code, try to answer the following questions:

• How will money move in my product?
• What balances need to exist to support this movement?
• Who will own these balances?

In Blnk, every event is represented as a transaction. Wallet funding, staking, currency exchange, refunds, fees, settlements, etc. are all different workflows that create one or more transactions.

A well-designed ledger makes the rest of your system simpler, predictable, and most important of all, auditable.

This is why Blnk gives you the primitives like ledgers, balances, transactions, and identities directly so you can mix and match to design the best architecture for your product.

Think ledger-first

Your ledger serves as your source of truth.

Where possible, avoid playing catch-up with your ledger. Events and logic relating to money movement should always begin in the ledger before continuing elsewhere in your code.

As a rule of thumb:

• If a rule affects money, it should show up first in the ledger.
• Avoid encoding ledger logic in application code first. The ledger should define how you process transactions.

This matters because events could get lost in transit before hitting your ledger from third-parties leading to an unreliable source of truth (which we don't want). With ledger-first, events are recorded in your ledger first before being processed in your application.

If the process is interrupted, you can always reference your ledger and replay it from there.

Use the queue

The most important thing you want your ledger to be is reliable.

You want to make sure that transactions get properly recorded, idempotency is handled correctly, better concurrency handling during high frequency, and that balances are always eventually correct.

One of the ways Blnk ensures this is the queue system. With queueing, transactions first enter a queue, and are then processed by the worker service.

This gives you:

• Reliability during high throughput/workloads
• Safer concurrency (by serializing transactions that act on the same balance)
• Clear recovery paths when things fail through graceful retries
• Full auditability and immutability

Once a transaction is processed, the records are immutable. Corrections can only be handled through new entries, not edits.

This makes reconciliation and debugging more straightforward months after you've shipped your ledger.

Customize your configuration

The blnk.json config is intentionally minimal by default.

However, Blnk comes with a lot of config options baked in. Configuration is where you adapt Blnk to your product.

That said, Blnk ships with a wide range of configuration options under the hood. Configuration is where you shape Blnk to match your product's behavior, not just its environment.

You can use config to control things like:

1. Enable secure mode and set your master secret key.
2. Manage your DB connection pools
3. Tune your workers to easily handle high throughput during spikes/at scale.
4. Configure global notifications via webhooks

As your workload grows and demand increases, configuration becomes a way to get more out of Blnk. You can gradually adjust how the system behaves to match your scale, performance needs, and operational requirements.

Build with Blnk Cloud

You deal with money. Instead of querying tables or running ad hoc scripts, use Blnk Cloud to manage and gain insights into what's happening in your ledger.

We designed Blnk Cloud to serve as your back-office ops tool. Use it to:

• Inspect balances, identities, and transactions.
• Create insights, analytics, and views to help you make better decisions.
• Investigate issues without touching the data directly.
• Invite your team to work with the ledger with access controls and permissions.

Cloud makes your ledger easier to observe and operate. If Core is the engine, Cloud is your back-office.

Deploy on the Cloud

Instead of provisioning servers, tuning databases, and worrying about uptime, with our Cloud deployment, you get a ready to run ledger instance designed to handle real workloads.

Improve your ledger's security

Avoid using your master key during integration. Instead, create granular API keys and use them intentionally.

```

--CODE language-bash--

curl -X POST 'http://localhost:5001/api-keys' \
 -h 'X-Blnk-Key: BLNK_API_KEY' \
 -h 'Content-Type: application/json' \
 -d '{
   "name": "Service Account",
   "owner": "owner_id",
   "scopes": ["ledgers:read", "balances:write"],
   "expires_at": "2026-03-11T00:00:00Z"
 }'

```

‍

When you create API keys in Blnk, each key is scoped to specific actions that you define. This lets you control exactly what a key can and cannot do.

Why this matters:

• Reduced blast radius. If a key is compromised, only a limited set of actions is affected. You can easily void just that key without affecting others.
• Clear audit trails. Every record created includes metadata showing which API key performed the action.
• Faster debugging. When something goes wrong, you can immediately trace it back to the exact service or integration responsible.
• Safer system design. You can enforce separation between services without adding custom logic.

A practical approach is to create one API key per service or integration that talks to the ledger.

Blnk then becomes the source of truth for tracking activity, enforcing permissions, and auditing changes across your financial system.

When something goes wrong

Failures happen. What matters is how quickly you can understand, investigate and recover.

Distributed tracing

• Blnk emits detailed traces across requests, workers, queues, and storage.
• Traces can be exported to any OpenTelemetry-compatible provider.
• Jaeger is included by default so you can visualize execution paths and spot slowdowns or breakpoints quickly.

Structured logs

• Logs are consistent and structured across services, entities, and state changes.
• They help you understand why a transaction failed, retried, or was delayed.
• Logs are available across both server and worker processes.

Error notifications

• Errors can be pushed to webhooks or Slack for faster awareness and response.
• This allows teams to react to issues as they happen, not after customers complain.

Queue visibility

• A built-in dashboard lets you monitor queue depth, processing state, and backlogs.
• This helps you detect pressure early and understand how work is flowing through the system.

Update your Blnk Core if outdated

‍

```

--CODE language-bash--

git pull || (git clone https://github.com/blnkfinance/blnk && cd blnk)
docker compose up -d

```

‍

Blnk is designed to be backward compatible. New versions are built so upgrades work out of the box, without breaking existing behavior or requiring risky migrations.

We regularly ship bug fixes, performance improvements, and stability enhancements in minor releases. In many cases, upgrading to the latest version is enough to resolve issues you're seeing.

Treat Core updates as routine maintenance, not emergency fixes. Staying up to date reduces the surface area for failures and makes debugging easier when issues do occur.

Ask for help

Ledger systems are hard by nature.

If something feels unclear, ask early. We're always happy to help on Discord or offer dedicated support to your team.

Get started with Blnk now: docs.blnkfinance.com