Configuration Reference

This page is a broad reference for common Blnk settings and typical defaults. The Blnk config package in the application repository is the source of truth; when in doubt, confirm keys and defaults in source. Fields with no defaults are left blank in the examples.

In blnk.json, most duration fields use integer seconds (lock_duration, lock_wait_timeout, hot_pair_ttl). Blnk multiplies them by time.Second on load.

Upgrade to Blnk Core 0.15.1 or later before setting BLNK_TRANSACTION_LOCK_DURATION manually. Earlier versions (0.10.3–0.15.0) can misapply Go duration values such as 1m. See the 0.15.1 migration guide.

server.ssl / BLNK_SERVER_SSL is honoured from 0.15.4. Through 0.12.x the flag worked. From 0.13.0 through 0.15.3 it was ignored. See HTTPS settings.

queue.backpressure_check_interval and typesense.backpressure_retry_interval use nanoseconds in JSON (for example 500000000 for 500ms). Environment variables for all duration fields use Go duration format (for example 500ms, 5s).

# Project
# Defaults to "Blnk Server" when not set.
BLNK_PROJECT_NAME=Blnk Server

# Server
# Port defaults to 5001. SSL and secure mode are off by default.
# From 0.15.4, BLNK_SERVER_SSL=true starts HTTPS. See Server & security.
BLNK_SERVER_SECURE=false
BLNK_SERVER_SECRET_KEY=
BLNK_SERVER_PORT=5001
BLNK_SERVER_SSL=false
BLNK_SERVER_SSL_DOMAIN=
BLNK_SERVER_SSL_EMAIL=
BLNK_CERT_STORAGE_PATH=/var/lib/blnk/certs
BLNK_SERVER_MAX_REQUEST_BODY_SIZE_MB=5
BLNK_SERVER_MAX_UPLOAD_SIZE_MB=256
BLNK_METRICS_BEARER_TOKEN=

# Database
# DNS is required for Blnk to start successfully. Docker default shown below.
# CONNECTION_MAX_LIFETIME and CONNECTION_MAX_IDLE_TIME are integer seconds.
BLNK_DATA_SOURCE_DNS=postgres://postgres:password@postgres:5432/blnk?sslmode=disable
BLNK_DATABASE_MAX_OPEN_CONNS=50
BLNK_DATABASE_MAX_IDLE_CONNS=25
BLNK_DATABASE_CONN_MAX_LIFETIME=30m
BLNK_DATABASE_CONN_MAX_IDLE_TIME=5m

# Redis
# DNS is required for Blnk to start successfully. Docker default shown below.
BLNK_REDIS_DNS=redis:6379
BLNK_REDIS_SKIP_TLS_VERIFY=false

# Typesense
# Docker default shown for the Typesense endpoint. The API key defaults to "blnk-api-key".
BLNK_TYPESENSE_DNS=http://typesense:8108
BLNK_TYPESENSE_KEY=blnk-api-key
BLNK_TYPESENSE_BACKPRESSURE_RETRY_INTERVAL=5s

# Transactions
# LOCK_DURATION and LOCK_WAIT_TIMEOUT are integer seconds.
BLNK_TRANSACTION_BATCH_SIZE=1000
BLNK_TRANSACTION_MAX_QUEUE_SIZE=1000
BLNK_TRANSACTION_MAX_WORKERS=10
BLNK_TRANSACTION_LOCK_DURATION=1m
BLNK_TRANSACTION_LOCK_WAIT_TIMEOUT=3s
BLNK_TRANSACTION_INDEX_QUEUE_PREFIX=transactions
BLNK_TRANSACTION_ENABLE_COALESCING=true
BLNK_TRANSACTION_ENABLE_QUEUED_CHECKS=false
BLNK_TRANSACTION_DISABLE_BATCH_REFERENCE_CHECK=false

# Queue
BLNK_QUEUE_TRANSACTION=new:transaction
BLNK_QUEUE_WEBHOOK=new:webhook
BLNK_QUEUE_INDEX=new:index
BLNK_QUEUE_INFLIGHT_EXPIRY=new:inflight-expiry
BLNK_QUEUE_INFLIGHT_COMMIT=new:inflight-commit
BLNK_QUEUE_NUMBER_OF_QUEUES=20
BLNK_QUEUE_INSUFFICIENT_FUND_RETRIES=false
BLNK_QUEUE_MAX_RETRY_ATTEMPTS=5
BLNK_QUEUE_MONITORING_PORT=5004
BLNK_QUEUE_WEBHOOK_CONCURRENCY=20

# Hot-lane and worker tuning
# HOT_PAIR_TTL is integer seconds.
BLNK_QUEUE_ENABLE_HOT_LANE=false
BLNK_QUEUE_HOT_QUEUE_NAME=hot_transactions
BLNK_QUEUE_HOT_QUEUE_CONCURRENCY=1
BLNK_QUEUE_HOT_PAIR_TTL=300
BLNK_QUEUE_HOT_PAIR_LOCK_CONTENTION_THRESHOLD=3
BLNK_QUEUE_REJECT_LOCK_CONTENTION_IMMEDIATELY=false
BLNK_QUEUE_TRANSACTION_WORKER_CONCURRENCY=4
BLNK_QUEUE_ENABLE_BACKPRESSURE=true
BLNK_QUEUE_BACKPRESSURE_MEMORY_PERCENT=85
BLNK_QUEUE_BACKPRESSURE_MAX_PENDING_TASKS=0
BLNK_QUEUE_BACKPRESSURE_CHECK_INTERVAL=500ms

# Rate limiting
# These are the runtime defaults used when rate limiting is not configured. Values are integer seconds.
BLNK_RATE_LIMIT_RPS=5000000
BLNK_RATE_LIMIT_BURST=10000000
BLNK_RATE_LIMIT_CLEANUP_INTERVAL_SEC=10800

# Reconciliation
# Retry delay uses Go duration format.
BLNK_RECONCILIATION_DEFAULT_STRATEGY=one_to_one
BLNK_RECONCILIATION_PROGRESS_INTERVAL=100
BLNK_RECONCILIATION_MAX_RETRIES=3
BLNK_RECONCILIATION_RETRY_DELAY=5s

# Webhooks
# Leave these blank until you are ready to send Slack alerts or webhooks.
BLNK_SLACK_WEBHOOK_URL=
BLNK_WEBHOOK_URL=
BLNK_WEBHOOK_HEADERS={}

# Observability
BLNK_ENABLE_TELEMETRY=false
BLNK_ENABLE_OBSERVABILITY=false
# Blnk Cloud DSN for managed monitoring export. Format: https://<write-key>@<host>/<project-id>
BLNK_CLOUD_DSN=
# Self-hosted OTLP HTTP export (works when observability is enabled)
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=

# Tokenization
BLNK_TOKENIZATION_SECRET=

# Backups
BLNK_BACKUP_DIR=
BLNK_AWS_ACCESS_KEY_ID=
BLNK_AWS_SECRET_ACCESS_KEY=
BLNK_S3_ENDPOINT=
BLNK_S3_BUCKET_NAME=
BLNK_S3_REGION=

{
  "project_name": "Blnk Server",
  "server": {
    "secure": false,
    "secret_key": "",
    "port": "5001",
    "ssl": false,
    "domain": "",
    "ssl_email": "",
    "cert_storage_path": "/var/lib/blnk/certs",
    "metrics_bearer_token": "",
    "max_request_body_size_mb": 5,
    "max_upload_size_mb": 256
  },
  "data_source": {
    "dns": "postgres://postgres:password@postgres:5432/blnk?sslmode=disable",
    "max_open_conns": 50,
    "max_idle_conns": 25,
    "conn_max_lifetime": 1800,
    "conn_max_idle_time": 300
  },
  "redis": {
    "dns": "redis:6379",
    "skip_tls_verify": false,
    "pool_size": 100,
    "min_idle_conns": 20
  },
  "typesense": {
    "dns": "http://typesense:8108",
    "backpressure_retry_interval": 5000000000
  },
  "type_sense_key": "blnk-api-key",
  "transaction": {
    "batch_size": 1000,
    "max_queue_size": 1000,
    "max_workers": 10,
    "lock_duration": 60,
    "lock_wait_timeout": 3,
    "index_queue_prefix": "transactions",
    "enable_coalescing": true,
    "enable_queued_checks": false,
    "disable_batch_reference_check": false
  },
  "queue": {
    "transaction_queue": "new:transaction",
    "webhook_queue": "new:webhook",
    "index_queue": "new:index",
    "inflight_expiry_queue": "new:inflight-expiry",
    "inflight_commit_queue": "new:inflight-commit",
    "number_of_queues": 20,
    "insufficient_fund_retries": false,
    "max_retry_attempts": 5,
    "monitoring_port": "5004",
    "webhook_concurrency": 20,
    "enable_hot_lane": false,
    "hot_queue_name": "hot_transactions",
    "hot_queue_concurrency": 1,
    "hot_pair_ttl": 300,
    "hot_pair_lock_contention_threshold": 3,
    "reject_lock_contention_immediately": false,
    "transaction_worker_concurrency": 4,
    "enable_backpressure": true,
    "backpressure_memory_percent": 85,
    "backpressure_max_pending_tasks": 0,
    "backpressure_check_interval": 500000000
  },
  "rate_limit": {
    "requests_per_second": 5000000,
    "burst": 10000000,
    "cleanup_interval_sec": 10800
  },
  "reconciliation": {
    "default_strategy": "one_to_one",
    "progress_interval": 100,
    "max_retries": 3,
    "retry_delay": 5
  },
  "notification": {
    "slack": {
      "webhook_url": ""
    },
    "webhook": {
      "url": "",
      "headers": {}
    }
  },
  "enable_telemetry": false,
  "enable_observability": false,
  "cloud_dsn": "",
  "tokenization_secret": "",
  "backup_dir": "",
  "aws_access_key_id": "",
  "aws_secret_access_key": "",
  "s3_endpoint": "",
  "s3_bucket_name": "",
  "s3_region": ""
}

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.

Start Here

Ledgers

Ledger balances

Transactions

Reconciliation

Identities

Metadata

Search

Webhooks

API keys

Guides

Configuration

Advanced

Migration guides

Need help?

​Need help?

Need help?