Blnk Documentation

Blnk provides three primary functional pillars for financial applications:

Ledger

An open-source double-entry ledger for managing balances and recording transaction workflows. Key features include:

• Balance monitoring and snapshots.
• Historical balance tracking.
• Inflight transactions and scheduling.
• Overdraft management.
• Bulk transaction workflows.

Reconciliation

Tools to match external records (e.g., bank statements or payment processor exports) against internal ledger records using custom matching rules and reconciliation strategies.

Identity Management

Capabilities to create and manage identities, tokenize PII (Personally Identifiable Information), and link identities directly to balances and transactions.

Developers use Blnk to build various financial workflows, including:

• Wallet management
• Deposits and withdrawals
• Order exchange (e.g., crypto)
• Lending products
• Loyalty points systems
• AI billing
• Escrow applications

Blnk supports two modes for exporting metrics:

• Pull (Prometheus): Prometheus scrapes the /metrics endpoint. This is always active when observability is enabled.
• Push (OTLP HTTP): Blnk periodically pushes metrics to an OpenTelemetry Collector. This mode is activated when OTEL_EXPORTER_OTLP_METRICS_ENDPOINT or OTEL_EXPORTER_OTLP_ENDPOINT is set.

If server.secure is enabled, the /metrics endpoint requires a bearer token.

1. Define the token in blnk.json using the key "metrics_bearer_token": "<your-token>" or via the environment variable BLNK_METRICS_BEARER_TOKEN.
2. Configure your Prometheus scraper to include this token in the authorization header.

If secure mode is enabled but no token is configured, the endpoint will return 403 Forbidden.

scrape_configs:
  - job_name: 'blnk-server'
    authorization:
      type: Bearer
      credentials: '<your-token>'
    static_configs:
      - targets: ['server:5001']

Blnk exposes OpenTelemetry metrics via a Prometheus-compatible /metrics endpoint. To use metrics, you must first enable observability in your configuration.

1. Enable Observability

Set "enable_observability": true in your blnk.json file, or set the environment variable BLNK_ENABLE_OBSERVABILITY=true.

2. Access Endpoints

• Server: GET /metrics on the API port (default 5001).
• Worker: GET /metrics on the monitoring port (default 5004).

Blnk is an open-source, double-entry ledger designed for fintech applications like wallets, banking infrastructure, and payment systems. To begin using Blnk, follow these steps:

1. Installation: You can either install Blnk locally or deploy a sandbox on Blnk Cloud.
2. Initial Setup: Follow the tutorial to create your first ledger, balance, and transaction.
3. Learning: Explore existing Blnk tutorials or consult the API reference for detailed technical specifications.

Blnk's hook execution engine follows specific rules to determine if a webhook attempt was successful:

1. HTTP Status Codes: A status code in the 2xx range is generally treated as success.
2. Empty Responses: If the response body is empty and the status is 2xx, the hook is marked as successful.
3. Non-JSON Responses: If the response is not valid JSON but the status is 2xx, the hook is marked as successful (with a warning logged).
4. JSON Responses: If the response is valid JSON, Blnk attempts to unmarshal it into a HookResponse object. The execution is only considered successful if the Success field in the JSON is true.
5. Error Handling: If the status is 4xx or 5xx, or if the JSON response contains "success": false, the hook is marked as failed.

When receiving webhooks from Blnk, you must verify the authenticity of the request using the provided signature. Blnk uses an HMAC-SHA256 signature based on a shared secret.

Signature Construction:

1. Obtain the X-Blnk-Timestamp from the request header.
2. Retrieve the raw JSON request body.
3. Create a string in the format: {timestamp}.{payload}.
4. Compute the HMAC-SHA256 signature of that string using your Server.SecretKey.
5. Compare your computed signature with the value in the X-Blnk-Signature header.

Required Headers:

• X-Blnk-Signature: The HMAC-SHA256 signature.
• X-Blnk-Timestamp: The timestamp used to generate the signature.
• X-Hook-ID: The unique identifier for the hook.
• X-Hook-Type: The type of hook being executed.
• Content-Type: Must be application/json.

Blnk can automatically split a single transaction into multiple transactions using the SplitTransactionPrecise method on the model.Transaction type.

When QueueTransaction is called, it invokes handleSplitTransactions. If the transaction is splittable, the resulting slice of transactions is processed. Each split transaction is assigned a new reference following the pattern {original_reference}_{index} (e.g., ref_1, ref_2) and maintains a link to the original via the ParentTransaction field.

When defining MatchingCriteria, ensure the AllowableDrift is appropriate for the field and operator:

• amount (with equals): Drift is a fraction of the amount (e.g., 0.01 allows a 1% deviation).
• date (with equals): Drift is measured in seconds.
• description/reference/currency (with contains): Uses Levenshtein distance for fuzzy string matching based on a percentage drift.