Set Up Your Blnk Configuration • Blnk Developer Documentation

Overview

Customise your Blnk server with our robust configuration system. This configuration is set via the blnk.json file or environment variables with the prefix, BLNK_.

Configuration structure

Server configuration

The server configuration module provides a centralized way to define your server’s behavior and security settings..

{
  "server": {
    "ssl": false,                  
    "secure": false,               
    "secret_key": "",          
    "domain": "",              
    "email": "",               
    "port": "5001"             
  }
}

Attribute	Type	Description	Environment variables
`ssl`	boolean	Controls SSL/TLS encryption for secure communications. When enabled, the server will require HTTPS connections and handle SSL certificate management.	`BLNK_SERVER_SSL`
`secure`	boolean	Enables enhanced security mode with additional protection mechanisms such as strict HTTP headers, CORS policies, and request validation.	`BLNK_SERVER_SECURE`
`secret_key`	string	Used for session encryption, token signing, and other cryptographic operations. Should be a strong, unique value in production.	`BLNK_SERVER_SECRET_KEY`
`domain`	string	Specifies the domain name for SSL certificate configuration and cookie settings. Required when SSL is enabled.	`BLNK_SERVER_SSL_DOMAIN`
`email`	string	Contact email address for SSL certificate registration and notifications. Required for automated SSL certificate management.	`BLNK_SERVER_SSL_EMAIL`
`port`	string	The network port on which the server listens for incoming connections.	`BLNK_SERVER_PORT`

PII tokenization

This configuration ensures that sensitive data is encrypted and protected during tokenization and detokenization operations.

{
  "tokenization_secret": ""
}

Attribute	Type	Description	Environment variables
`tokenization_secret`	string	Secret key used to secure the tokenization process.	`BLNK_TOKENIZATION_SECRET`

Database configuration

The data source configuration establishes the connection between the Blnk server and your database backend, including connection pooling settings for optimal performance.

{
  "data_source": {
    "dns": "",
    "max_open_conns": 25,
    "max_idle_conns": 10,
    "conn_max_lifetime": "30m",
    "conn_max_idle_time": "5m"
  }
}

Attribute	Type	Description	Environment variables
`dns`	string	The database connection string that specifies the location, credentials, and parameters for connecting to your database. Required for server startup.	`BLNK_DATA_SOURCE_DNS`
`max_open_conns`	integer	Maximum number of open connections to the database. Controls the size of the connection pool.	`BLNK_DATABASE_MAX_OPEN_CONNS`
`max_idle_conns`	integer	Maximum number of idle connections in the pool. Should be less than or equal to max_open_conns.	`BLNK_DATABASE_MAX_IDLE_CONNS`
`conn_max_lifetime`	duration	Maximum amount of time a connection may be reused. Use Go duration format (e.g., “30m”, “1h”).	`BLNK_DATABASE_CONN_MAX_LIFETIME`
`conn_max_idle_time`	duration	Maximum amount of time a connection may be idle before being closed. Use Go duration format (e.g., “5m”, ”10s”).	`BLNK_DATABASE_CONN_MAX_IDLE_TIME`

The DNS string typically follows this pattern: [driver]://[username]:[password]@[host]:[port]/[database]

Redis configuration

The Redis configuration manages the connection to your Redis instance, which is commonly used for caching, session storage, and message queuing.

{
  "redis": {
    "dns": "",
    "skip_tls_verify": false
  }
}

Attribute	Type	Description	Environment variables
`dns`	string	The Redis connection string that specifies the host, port, and authentication details for your Redis instance. Required for Redis functionality.	`BLNK_REDIS_DNS`
`skip_tls_verify`	boolean	If true, disables TLS certificate verification for Redis connections. Useful for self-signed or untrusted certificates. Defaults to false.	`BLNK_REDIS_SKIP_TLS_VERIFY`

Typesense configuration

The TypeSense configuration manages your connection to the TypeSense search engine, enabling fast and typo-tolerant search functionality in your Blnk server.

{
  "typesense": {
    "dns": ""                         
  },
  "type_sense_key": ""               
}

Attribute	Type	Description	Environment variables
`dns`	string	The URL endpoint for your TypeSense server instance. Specifies the host and port for the TypeSense connection.	`BLNK_TYPESENSE_DNS`
`type_sense_key`	string	The API key used for authenticating requests to your TypeSense instance. Required for secure access to the search engine.	`BLNK_TYPESENSE_KEY`

Rate limiting

The rate limiting configuration helps protect the API from abuse and ensures fair resource allocation.

{
  "rate_limit": {
    "requests_per_second": 1000,     
    "burst": 1000,                   
    "cleanup_interval_sec": 60    
  }
}

Attribute	Type	Description	Environment variables
`requests_per_second`	number/null	Maximum number of requests allowed per second per client. When `null`, no RPS limit is applied.	`BLNK_RATE_LIMIT_RPS`
`burst`	number/null	Maximum number of requests allowed to exceed the RPS limit in short bursts. When `null`, no burst limit is applied.	`BLNK_RATE_LIMIT_BURST`
`cleanup_interval_sec`	number	Interval in seconds for cleaning up expired rate limit data. Defaults to 1 minute.	`BLNK_RATE_LIMIT_CLEANUP_INTERVAL_SEC`

Transaction configuration

The transaction configuration manages how Blnk processes and handles batched operations, controlling throughput and resource utilization.

{
  "transaction": {
    "batch_size": 100000,                
    "max_queue_size": 1000,              
    "max_workers": 10,                   
    "lock_duration": 1800,               
    "index_queue_prefix": "transactions",
    "enable_queued_checks": false
  }
}

Attribute	Type	Description	Environment variables
`batch_size`	number/null	Maximum number of items to process in a single transaction batch.	`BLNK_TRANSACTION_BATCH_SIZE`
`max_queue_size`	number/null	Maximum number of transactions that can be queued for processing.	`BLNK_TRANSACTION_MAX_QUEUE_SIZE`
`max_workers`	number	Maximum number of concurrent workers processing transactions.	`BLNK_TRANSACTION_MAX_WORKERS`
`lock_duration`	number	Duration for which a transaction lock is held. Format: seconds.	`BLNK_TRANSACTION_LOCK_DURATION`
`index_queue_prefix`	string	Prefix used for the transaction queue names in the indexing system.	`BLNK_TRANSACTION_INDEX_QUEUE_PREFIX`
`enable_queued_checks`	boolean	Enables additional validation checks for queued transactions before processing.	`BLNK_TRANSACTION_ENABLE_QUEUED_CHECKS`

Reconciliation configuration

The reconciliation configuration handles how the reconciliation engine works.

{
  "reconciliation": {
    "default_strategy": "one_to_one",     
    "progress_interval": 100,             
    "max_retries": 3,                     
    "retry_delay": 5                      
  }
}

Attribute	Type	Description	Environment variables
`default_strategy`	string	Defines the default matching strategy for reconciliation. Options are `one_to_one`, `one_to_many`, `many_to_one`.	`BLNK_RECONCILIATION_DEFAULT_STRATEGY`
`progress_interval`	number	Number of records to process before emitting a progress update.	`BLNK_RECONCILIATION_PROGRESS_INTERVAL`
`max_retries`	number	Maximum number of retry attempts for failed reconciliation operations.	`BLNK_RECONCILIATION_MAX_RETRIES`
`retry_delay`	string	Time to wait between retry attempts. Format: seconds.	`BLNK_RECONCILIATION_RETRY_DELAY`

Queue configuration

The queue configuration defines the various queues used throughout the server for processing different types of operations asynchronously.

{
  "queue": {
    "transaction_queue": "new:transaction",             
    "webhook_queue": "new:webhook",                     
    "index_queue": "new:index",                         
    "inflight_expiry_queue": "new:inflight-expiry",     
    "number_of_queues": 20,
    "insufficient_fund_retries": true,
    "max_retry_attempts": 3,
    "monitoring_port": "5004"
  }
}

Attribute	Type	Description	Environment variables
`transaction_queue`	string	Queue name for processing transaction operations.	`BLNK_QUEUE_TRANSACTION`
`webhook_queue`	string	Queue name for handling webhook event delivery.	`BLNK_QUEUE_WEBHOOK`
`index_queue`	string	Queue name for managing search index updates.	`BLNK_QUEUE_INDEX`
`inflight_expiry_queue`	string	Queue name for tracking and processing in-flight operation timeouts.	`BLNK_QUEUE_INFLIGHT_EXPIRY`
`number_of_queues`	number	Total number of queue workers to maintain across all queue types.	`BLNK_QUEUE_NUMBER_OF_QUEUES`
`insufficient_fund_retries`	boolean	Determines whether the ledger should automatically retry transactions that fail due to insufficient funds.	`BLNK_QUEUE_INSUFFICIENT_FUND_RETRIES`
`max_retry_attempts`	number	Specifies the maximum number of retry attempts before the transaction with insufficient funds is rejected.	`BLNK_QUEUE_MAX_RETRY_ATTEMPTS`
`monitoring_port`	string	The network port on which the monitoring server listens for incoming connections.	`BLNK_QUEUE_MONITORING_PORT`

Notification configuration

The notification configuration manages external integrations for system notifications, including Slack alerts and custom webhooks.

{
  "notification": {
    "slack": {
      "webhook_url": ""
    },
    "webhook": {
      "url": "",
      "headers": {}     
    }
  }
}

Attribute	Type	Description	Environment variables
`slack.webhook_url`	string	Slack webhook URL for sending notifications to specific channels.	`BLNK_SLACK_WEBHOOK_URL`
`webhook.url`	string	Endpoint URL where webhook notifications will be sent.	`BLNK_WEBHOOK_URL`
`webhook.headers`	object	Custom HTTP headers to be included with webhook requests.	`BLNK_WEBHOOK_HEADERS`

S3 configuration

The S3 configuration manages connection settings for Amazon S3 storage service for system backups and file storage.

{
  "backup_dir": "",                      
  "aws_access_key_id": "",
  "aws_secret_access_key": "",
  "s3_endpoint": "",
  "s3_bucket_name": "",
  "s3_region": ""
}

Attribute	Type	Description	Environment variables
`backup_dir`	string	Directory path where backups will be stored in S3.	`BLNK_BACKUP_DIR`
`aws_access_key_id`	string	AWS access key ID for authentication.	`BLNK_AWS_ACCESS_KEY_ID`
`aws_secret_access_key`	string	AWS secret access key for authentication.	`BLNK_AWS_SECRET_ACCESS_KEY`
`s3_endpoint`	string	Custom endpoint URL for S3-compatible services. Leave empty for default AWS S3.	`BLNK_S3_ENDPOINT`
`s3_bucket_name`	string	Name of the S3 bucket to use for storage.	`BLNK_S3_BUCKET_NAME`
`s3_region`	string	AWS region where the S3 bucket is located (e.g., “us-east-1”).	`BLNK_S3_REGION`

Telemetry and observability

This configuration enables telemetry and observability features for monitoring and debugging.

{
  "enable_telemetry": true,
  "enable_observability": true
}

Attribute	Type	Description	Environment variables
`enable_telemetry`	boolean	Sends data to Jaeger for tracing and monitoring via OTLP. Defaults to `false` for privacy.	`BLNK_ENABLE_TELEMETRY`
`enable_observability`	boolean	Enables additional observability features like metrics collection and detailed logging.	`BLNK_ENABLE_OBSERVABILITY`

Default values & validation

Required fields

Data Source DNS (data_source.dns)
Redis DNS (redis.dns)

Automatic defaults

Server defaults:
- Project name: “Blnk Server”
- Server port: “5001”
- TypeSense key: “blnk-api-key”
- Tokenization secret: “blnk-default-tokenization-key!!!!” (⚠️ Change in production)
Database defaults:
- Max open connections: 25
- Max idle connections: 10
- Connection max lifetime: 30 minutes
- Connection max idle time: 5 minutes
Rate limiting:
- If RPS is set without burst, burst defaults to 2 * RPS
- If burst is set without RPS, RPS defaults to burst / 2
- Cleanup interval defaults to 10800 seconds (3 hours)
Privacy defaults:
- Telemetry is disabled by default (opt-in for privacy)
- Observability is disabled by default

Transaction defaults

Batch size: 100,000
Max queue size: 1,000
Max workers: 10
Lock duration: 30 minutes
Index queue prefix: “transactions”
Enable queued checks: false

Reconciliation defaults

Default strategy: “one_to_one”
Progress interval: 100
Max retries: 3
Retry delay: 5 seconds

Queue defaults

Transaction queue: “new:transaction”
Webhook queue: “new:webhook”
Index queue: “new:index”
Inflight expiry queue: “new:inflight-expiry”
Number of queues: 20
Monitoring port: “5004”

Configuration loading process

Load configuration from JSON file if present.
Override with environment variables.
Validate required fields.
Apply default values.
Trim whitespace from string values.
Setup rate limiting defaults.

Need help?

We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool. To ask questions or discuss issues, please contact us or join our Discord community.

Getting Started

Ledgers

Ledger Balances

Transactions

Reconciliation

Identities

Metadata

Hooks

Search

Guides

Advanced

Configuring your Blnk server

Overview

Configuration structure

Server configuration

PII tokenization

Database configuration

Redis configuration

Typesense configuration

Rate limiting

Transaction configuration

Reconciliation configuration

Queue configuration

Notification configuration

S3 configuration

Telemetry and observability

Default values & validation

Required fields

Automatic defaults

Transaction defaults

Reconciliation defaults

Queue defaults

Configuration loading process

Need help?

Getting Started

Ledgers

Ledger Balances

Transactions

Reconciliation

Identities

Metadata

Hooks

Search

Guides

Advanced

​Overview

​Configuration structure

​Server configuration

​PII tokenization

​Database configuration

​Redis configuration

​Typesense configuration

​Rate limiting

​Transaction configuration

​Reconciliation configuration

​Queue configuration

​Notification configuration

​S3 configuration

​Telemetry and observability

​Default values & validation

​Required fields

​Automatic defaults

​Transaction defaults

​Reconciliation defaults

​Queue defaults

​Configuration loading process

​Need help?

Overview

Configuration structure

Server configuration

PII tokenization

Database configuration

Redis configuration

Typesense configuration

Rate limiting

Transaction configuration

Reconciliation configuration

Queue configuration

Notification configuration

S3 configuration

Telemetry and observability

Default values & validation

Required fields

Automatic defaults

Transaction defaults

Reconciliation defaults

Queue defaults

Configuration loading process

Need help?