Skip to main content

​
Introduction

The Blnk API is a comprehensive REST API designed for managing ledgers, balances, transactions, and financial operations. Built with high performance and reliability in mind, it provides a complete double-entry accounting system with advanced features like real-time balance monitoring, reconciliation, and search capabilities.

​
Base URL

The API runs on a configurable port (default: 5001): 
http://localhost:5001
For production deployments, replace localhost with your server’s domain.

​
API Architecture

The Blnk API follows RESTful principles:
  • Resource-based URLs: Each endpoint represents a specific resource (ledgers, balances, transactions, etc.)
  • HTTP methods: Standard methods (GET, POST, PUT, DELETE) for CRUD operations
  • JSON format: All requests and responses use JSON
  • Stateless: Each request contains all information needed for processing

​
Request Format

All API requests must include:
​
Content-Type
string
required
Set to application/json for all requests with body content
​
X-Blnk-Key
string
required
Your API key or master key for authentication (when secure mode is enabled)

​
Example Request

curl -X POST http://localhost:5001/ledgers \
  -H "Content-Type: application/json" \
  -H "X-Blnk-Key: your-api-key" \
  -d '{
    "name": "Customer Ledger",
    "meta_data": {
      "project": "mobile-app"
    }
  }'

​
Response Format

All API responses are returned in JSON format with appropriate HTTP status codes.

​
Success Response

{
  "ledger_id": "ldg_1234567890",
  "name": "Customer Ledger",
  "created_at": "2024-03-04T10:30:00Z",
  "meta_data": {
    "project": "mobile-app"
  }
}

​
Error Response

Errors return a JSON object with an error field: 
{
  "error": "Invalid request: name is required"
}
See Error Reference for detailed error codes and meanings.

​
Rate Limiting

The Blnk API implements rate limiting to ensure fair usage and system stability.
​
requests_per_second
number
default:"5000000"
Maximum requests per second allowed
​
burst
number
default:"10000000"
Maximum burst capacity for handling traffic spikes

​
Rate Limit Headers

When rate limiting is active, responses include:
  • Rate limit information is managed server-side
  • Exceeded limits return HTTP 429 (Too Many Requests)
  • The cleanup interval for rate limit data is 10800 seconds (3 hours) by default

​
Configuration

Rate limits can be configured via environment variables: 
BLNK_RATE_LIMIT_RPS=5000000
BLNK_RATE_LIMIT_BURST=10000000
BLNK_RATE_LIMIT_CLEANUP_INTERVAL_SEC=10800

​
Pagination

Endpoints that return lists support pagination using query parameters:
​
limit
integer
default:"10"
Number of records to return (minimum: 1)
​
offset
integer
default:"0"
Number of records to skip (minimum: 0)

​
Example

GET /ledgers?limit=20&offset=40
This returns records 41-60 (20 records starting from the 41st).

​
Filtering

Many endpoints support advanced filtering through query parameters or request body.

​
Query Parameter Filters

Use the format field_operator=value: 
GET /balances?currency_eq=USD&created_at_gte=2024-01-01
Supported operators:
  • eq: Equal to
  • ne: Not equal to
  • gt: Greater than
  • gte: Greater than or equal to
  • lt: Less than
  • lte: Less than or equal to
  • in: In list (comma-separated)
  • ilike: Case-insensitive pattern match (use % as wildcard)

​
POST Filter Endpoints

For complex filters, use dedicated filter endpoints: 
POST /balances/filter

{
  "filters": [
    {"field": "currency", "operator": "eq", "value": "USD"},
    {"field": "ledger_id", "operator": "in", "values": ["ldg_123", "ldg_456"]}
  ],
  "limit": 20,
  "offset": 0,
  "include_count": true
}

​
API Resources

The Blnk API provides the following core resources:

​
Ledgers

Manage top-level ledger containers for organizing balances.

​
Balances

Track account balances with multi-currency support and real-time updates.

​
Transactions

Record and process double-entry financial transactions.

​
Identities

Store customer/entity information with tokenization support.

​
Accounts

Manage account records linked to balances.

​
API Keys

Manage authentication keys with granular permissions.

​
Additional Features

  • Search: Full-text search across resources using Typesense
  • Reconciliation: Match and reconcile internal vs external data
  • Webhooks: Configure event notifications
  • Backup: Database backup to local storage or S3

​
Getting Started

​
1. Set Up Authentication

First, configure your master key or create an API key: 
export BLNK_SERVER_SECRET_KEY="your-master-key"
Or create an API key programmatically (see Authentication).

​
2. Create a Ledger

curl -X POST http://localhost:5001/ledgers \
  -H "Content-Type: application/json" \
  -H "X-Blnk-Key: your-master-key" \
  -d '{"name": "Main Ledger"}'

​
3. Create a Balance

curl -X POST http://localhost:5001/balances \
  -H "Content-Type: application/json" \
  -H "X-Blnk-Key: your-master-key" \
  -d '{
    "ledger_id": "ldg_1234567890",
    "currency": "USD"
  }'

​
4. Record a Transaction

curl -X POST http://localhost:5001/transactions \
  -H "Content-Type: application/json" \
  -H "X-Blnk-Key: your-master-key" \
  -d '{
    "amount": 10000,
    "precision": 100,
    "reference": "ref_123",
    "currency": "USD",
    "source": "bln_source_id",
    "destination": "bln_dest_id"
  }'
The amount is specified in the smallest currency unit (e.g., cents). The precision field (100) indicates the actual amount is $100.00.

​
Security

  • Secure Mode: Enable authentication by setting BLNK_SERVER_SECURE=true
  • TLS/SSL: Configure SSL for production deployments
  • API Key Scopes: Limit access to specific resources and actions
  • Master Key: Full access key for administrative operations
See Authentication for detailed security configuration.

​
Observability

Blnk provides built-in observability features: 
BLNK_ENABLE_OBSERVABILITY=true  # Enable OpenTelemetry tracing
BLNK_ENABLE_TELEMETRY=true      # Enable usage telemetry
Monitoring endpoint runs on port 5004 by default.

​
Support

For issues and questions:

Build docs developers (and LLMs) love

Get started for freeTalk to us