Overview

Documentation Index

Fetch the complete documentation index at: https://docs.finwatch.finance/llms.txt

Use this file to discover all available pages before exploring further.

​

Getting Started with FinWatch

​

What is FinWatch?

1. The Watch Script DSL — A purpose-built domain-specific language for writing fraud detection rules. Rules are stored as .ws files that can be versioned in Git, reviewed in pull requests, and deployed with the same rigour as your application code. The language is designed to express complex fraud patterns — velocity checks, time-based anomalies, sequential behaviour analysis — in a readable, declarative format.
2. An Embedded Analytical Engine — FinWatch uses DuckDB, a high-performance embedded analytical database, to store and query transaction data locally. This means aggregate functions like “count the number of transactions from this account in the last 24 hours” execute in milliseconds without requiring a round-trip to an external database. DuckDB’s columnar storage and vectorised execution engine are optimised for exactly this type of analytical workload.
3. GitOps-Native Rule Management — Rules can be synced from a Git repository, enabling a full CI/CD lifecycle for fraud logic; write a rule, open a PR, get it reviewed by your compliance team, merge, and FinWatch picks it up automatically. Every change is audited, every version is recoverable.

​

Prerequisites

• Docker (recommended) — Install Docker
• curl — For sending HTTP requests from the command line. Pre-installed on macOS and most Linux distributions.
• A text editor — For writing .ws rule files. Any editor works; VS Code is recommended.
• Basic terminal knowledge — You should be comfortable running commands in a terminal.

• Go 1.21+ — Install Go
• Git — For cloning the repository and (optionally) for GitOps rule management.

​

Installation

​

Docker

docker run -d \
  --name finwatch \
  -p 8081:8081 \
  -e WATCH_SCRIPT_DIR=/app/watch_scripts \
  -v $(pwd)/my_rules:/app/watch_scripts \
  finwatch/finwatch:latest

• Starts FinWatch in the background (-d).
• Maps port 8081 on your host to port 8081 in the container.
• Sets the watch script directory to /app/watch_scripts inside the container.
• Mounts a local directory (my_rules/) so you can add and edit rule files from your host machine.

curl http://localhost:8081/instructions

​

Environment Variables

​

Your First Transaction

curl -X POST http://localhost:8081/inject \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "txn_001",
    "amount": 15000.00,
    "currency": "USD",
    "source": "acct_alice_123",
    "destination": "acct_bob_456",
    "reference": "invoice_2026_001",
    "description": "Consulting payment",
    "status": "pending",
    "created_at": "2026-04-18T14:30:00Z",
    "meta_data": {
      "ip_address": "192.168.1.100",
      "destination_country": "US",
      "device_type": "mobile"
    }
  }'

​

Your First Rule

mkdir -p my_rules

rule HighValueCheck {
    description "Flags any transaction over $10,000 for manual review."

    when amount > 10000

    then review
         score  0.7
         reason "Transaction amount exceeds $10,000 high-value threshold"
}

• Name: HighValueCheck — A clear, descriptive identifier.
• Description: Explains the rule’s purpose in plain English for auditors and analysts.
• Condition (when): Checks if the transaction’s amount field is greater than 10000.
• Action (then):
  • Verdict: review — Flag for human analyst review (don’t hard-block).
  • Score: 0.7 — High confidence that this warrants attention.
  • Reason: A clear explanation that will appear in logs and dashboards.

INF Compiled watch script: HighValueCheck

​

Testing the Rule

curl -X POST http://localhost:8081/inject \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "txn_002",
    "amount": 15000.00,
    "currency": "USD",
    "source": "acct_alice_123",
    "destination": "acct_bob_456",
    "reference": "invoice_2026_002",
    "description": "Consulting payment",
    "status": "pending",
    "meta_data": {
      "destination_country": "US"
    }
  }'

curl -X POST http://localhost:8081/inject \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "txn_003",
    "amount": 500.00,
    "currency": "USD",
    "source": "acct_charlie_789",
    "destination": "acct_dave_012",
    "reference": "coffee_shop_001",
    "description": "Coffee purchase"
  }'

​

What Just Happened?

1. Ingestion: The HTTP handler receives the JSON payload and decodes it into a Transaction struct.
2. Storage: The transaction is inserted into the local DuckDB transactions table. This makes it available for aggregate queries by other rules.
3. Rule Evaluation: The engine loads all compiled rules and evaluates them against the transaction. Each rule’s when clause is checked. If it evaluates to true, the then clause produces a RiskVerdict.
4. Risk Consolidation: All verdicts are aggregated. The final risk score, verdict, and reason are determined.
5. Anomaly Reporting: If the final verdict warrants it, an anomaly notification is sent to the FinWatch Cloud dashboard via the WebSocket tunnel for real-time alerting.

​

Next Steps

• Writing Your First Rule — A deeper tutorial on building rules step by step.
• Conditions Deep Dive — Learn every operator, logical combinator, and pattern matching technique available in the when clause.
• Aggregate Functions Guide — The most powerful feature of the DSL: detecting fraud patterns over time using count(), sum(), avg(), and more.
• The Rule Cookbook — A library of production-ready rule patterns you can copy and customise.
• DSL Reference — The complete language reference for the Watch Script DSL.
• API Documentation — Full REST API reference for all FinWatch endpoints.