Configuration

Blnk Watch is currently in beta. Send us a message

Blnk Watch is configured with environment variables, usually through a .env file. The minimum configuration you need to add is DB_URL so Watch can read and sync transactions from Blnk Core when you run start, sync, or sync-once. Watch loads .env by default.

Minimum required .env

# If using start, sync, or sync-once
DB_URL=postgres://user:password@localhost:5432/blnk?sslmode=disable

Core connection configuration

Use these settings when Watch needs to read transactions from Blnk Core. This is required for start, sync, and sync-once. It is not required if you run watch in API-only mode and inject transactions manually.

.env

# Blnk Core database connection string
DB_URL=postgres://user:password@localhost:5432/blnk?sslmode=disable

Variable	Description	Default	Required
`DB_URL`	PostgreSQL connection string for the Blnk Core database. Watch uses this for watermark sync and historical transaction processing.	None	Conditional

Rule source configuration

These settings control where Watch loads rules from. You can load rules from a local directory or point Watch at a Git repository that contains .ws rule files. If you set WATCH_SCRIPT_GIT_REPO, Watch clones the repository into WATCH_SCRIPT_DIR, processes the rules there, and keeps that local copy in sync.

.env

# Local directory only (default)
WATCH_SCRIPT_DIR=watch_scripts

# With Git-based rule loading
WATCH_SCRIPT_GIT_REPO=https://github.com/your-org/watch-rules.git
WATCH_SCRIPT_GIT_BRANCH=main

# Private HTTPS repos only (optional)
WATCH_SCRIPT_GIT_USERNAME=x-access-token
WATCH_SCRIPT_GIT_TOKEN=

Variable	Description	Default	Required
`WATCH_SCRIPT_DIR`	Local directory Watch reads for `.ws` rule files. This is also the destination directory when Git-based rule loading is enabled.	`watch_scripts`	No
`WATCH_SCRIPT_GIT_REPO`	Git repository URL containing Watch rules. When set, Watch pulls rules from this repository instead of relying only on local files.	None	No
`WATCH_SCRIPT_GIT_BRANCH`	Git branch Watch should track when `WATCH_SCRIPT_GIT_REPO` is set.	`main`	No
`WATCH_SCRIPT_GIT_USERNAME`	Username for private HTTPS Git clones. If you embed credentials in the repo URL, Watch extracts them and keeps the stored URL clean in logs and status responses.	`x-access-token`	No
`WATCH_SCRIPT_GIT_TOKEN`	Personal access token or password used with `WATCH_SCRIPT_GIT_USERNAME` for private HTTPS repositories. Store this as a secret.	None	No

Git-based rule loading requires git to be installed on the machine running Watch. For private HTTPS repositories, set WATCH_SCRIPT_GIT_TOKEN (and optionally WATCH_SCRIPT_GIT_USERNAME). For SSH URLs, load the appropriate SSH key on the host instead.

Core sync configuration

These settings apply when Watch syncs transaction data from Blnk Core (e.g. with start, sync, or sync-once). They control where the initial sync starts when there is no saved sync progress yet. They do not control rule evaluation. Use SYNC_TRANSACTION_LOOKBACK when you want Watch to start from a relative window (e.g. the last 48 hours). Use SYNC_TRANSACTION_START_TIME when you want a fixed start time. If both are set, SYNC_TRANSACTION_START_TIME takes precedence.

.env

# Relative lookback (e.g. last 48 hours)
SYNC_TRANSACTION_LOOKBACK=48h

# Or fixed start time (overrides lookback when set)
SYNC_TRANSACTION_START_TIME=2026-03-11T00:00:00Z

Variable	Description	Default	Required
`SYNC_TRANSACTION_LOOKBACK`	How far back to sync when starting (e.g. `48h`, `168h`). Go duration format.	`48h`	No
`SYNC_TRANSACTION_START_TIME`	Absolute starting point for the initial sync. Accepted formats are `2026-03-11T00:00:00Z`, `2026-03-11 15:04:05`, or `2026-03-11`.	None	No

Alert webhook configuration

These settings control alert webhook delivery when one or more rules are triggered by a transaction within Watch. Watch can send alerts to a primary webhook and fall back to secondary or backup endpoints if needed.

.env

ALERT_WEBHOOK_URL=https://your-server.com/alerts

ALERT_WEBHOOK_SECONDARY_URL=https://your-server.com/alerts-secondary
ALERT_WEBHOOK_BACKUP_URL=https://your-server.com/alerts-backup

ALERT_WEBHOOK_API_KEY=your_api_key_here

ALERT_WEBHOOK_RISK_THRESHOLD=0.5

ALERT_WEBHOOK_ENABLED=true

Variable	Description	Default	Required
`ALERT_WEBHOOK_URL`	Primary alert webhook URL.	None	No
`ALERT_WEBHOOK_SECONDARY_URL`	Secondary fallback alert webhook URL. Watch uses it if the primary webhook fails.	None	No
`ALERT_WEBHOOK_BACKUP_URL`	Final fallback alert webhook URL. Watch uses it if earlier webhook attempts fail.	None	No
`ALERT_WEBHOOK_API_KEY`	Bearer token sent in the `Authorization` header for alert webhook requests.	None	No
`ALERT_WEBHOOK_RISK_THRESHOLD`	Minimum risk score that should trigger an alert.	`0.5`	No
`ALERT_WEBHOOK_ENABLED`	Enables or disables alert webhook delivery. Set it to `false` to disable.	`true`	No

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

Watch scripts

Advanced

Core connection configuration

Rule source configuration

Core sync configuration

Alert webhook configuration

Need help?

​Core connection configuration

​Rule source configuration

​Core sync configuration

​Alert webhook configuration

​Need help?

Core connection configuration

Rule source configuration

Core sync configuration

Alert webhook configuration

Need help?