Introduction - FinWatch

The FinWatch API provides a REST interface for real-time transaction monitoring, rule evaluation, and instruction management. With this API, you can inject transactions for risk evaluation, define monitoring rules using the Watchscript DSL, and integrate with Git for version-controlled rule management. This guide is designed to help developers of all experience levels get started with FinWatch. If you’re new to APIs or transaction monitoring, don’t worry — we’ll walk you through everything step by step.

What is FinWatch?

FinWatch is an embedded domain-specific language (DSL) for monitoring financial transactions in real-time. It helps businesses detect fraud, enforce compliance, automate reconciliation, and manage risk by evaluating transactions against custom rules. When you send a transaction to FinWatch, it evaluates the transaction against your rules and returns a verdict — whether to approve, review, block, or alert — along with a risk score and reasoning.

Base URL

http://localhost:8081

All API endpoints are relative to this base URL. For example, to inject a transaction, you would send a POST request to http://localhost:8081/inject.

Quick Start

This quick start guide will walk you through the three most common tasks: injecting a transaction, creating a monitoring rule, and retrieving transaction details.

1. Inject a Transaction

The first step is to send a transaction to FinWatch for evaluation. This is how your application integrates with FinWatch — every transaction that needs monitoring should be sent to the /inject endpoint. Here’s an example using curl (a command-line tool for making HTTP requests):

curl -X POST http://localhost:8081/inject \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000.00,
    "currency": "USD",
    "source": "balance_123",
    "destination": "balance_456",
    "reference": "txn_ref_001",
    "description": "High-value transfer",
    "meta_data": {
      "merchant_category": "finance",
      "country": "US"
    }
  }'

What’s happening here:

We’re sending a POST request to the /inject endpoint
The Content-Type: application/json header tells the server we’re sending JSON data
The request body contains the transaction details:
- amount: The monetary value of the transaction
- currency: The currency code (e.g., USD, EUR)
- source and destination: Identifiers for the accounts involved
- reference: A unique identifier for this transaction
- meta_data: Additional context about the transaction (merchant category, country, etc.)

When you send this request, FinWatch evaluates the transaction against your rules and returns a response indicating whether the transaction should be approved, reviewed, blocked, or flagged for alert.

2. Create a Monitoring Rule

Before FinWatch can evaluate transactions, you need to define rules. Rules are written in Watchscript, FinWatch’s domain-specific language. A rule defines conditions to check and actions to take when those conditions are met. Here’s how to create a rule using the API:

curl -X POST http://localhost:8081/compile-and-save-instruction \
  -H "Content-Type: application/json" \
  -d '{
    "script": "rule HighValueTransaction {\n    description \"Review any transaction above $10,000\"\n    when amount > 10000\n    then review\n         score   0.5\n         reason  \"Amount exceeds threshold\"\n}"
  }'

Breaking down the rule:

rule HighValueTransaction — The name of the rule
description — A human-readable explanation of what the rule does
when amount > 10000 — The condition: if the transaction amount is greater than $10,000
then review — The action: mark the transaction for manual review
score 0.5 — A risk score from 0 to 1 (higher = more risky)
reason — The explanation that will be shown to analysts

When you send this request, FinWatch compiles the Watchscript and saves it as an instruction. From now on, any transaction injected will be evaluated against this rule.

3. Retrieve a Transaction

After injecting a transaction, you might want to retrieve its details later — for example, to check the evaluation result or for audit purposes. Here’s how to fetch a transaction by its ID:

curl http://localhost:8081/transactions/txn_123

Replace txn_123 with the actual transaction ID you want to retrieve. The response will include all the transaction details, including the evaluation result (verdict, score, and reason).

Authentication

Currently, the FinWatch API does not require authentication. This is convenient for development and testing environments. However, for production use, future versions will support API key-based authentication to secure access to your FinWatch instance.

Core Concepts

Understanding these core concepts will help you use the API effectively:

Transactions

A transaction represents a financial operation that needs to be evaluated against monitoring rules. Think of it as any money movement — a payment, a transfer, a withdrawal, etc. Each transaction includes:

Amount and currency — The monetary value (e.g., $5,000 USD)
Source and destination — Identifiers for the accounts or balances involved (e.g., balance IDs)
Reference — A unique identifier for the transaction (useful for tracking and reconciliation)
Metadata — Custom key-value pairs that provide context (e.g., merchant category, country, device ID)
Status — The current state of the transaction (e.g., pending, applied, failed)

When you inject a transaction, FinWatch evaluates it against all your active rules and returns a verdict.

Instructions (Rules)

Instructions are the monitoring rules that define how transactions should be evaluated. They’re written in Watchscript, FinWatch’s domain-specific language designed specifically for transaction monitoring. A rule consists of:

When clause — The conditions to evaluate (e.g., “when amount > 10,000”)
Then clause — The action to take when conditions are met (e.g., “review”, “block”, “alert”)
Score — A risk score from 0 to 1 (0 = low risk, 1 = high risk)
Reason — A human-readable explanation of why the action was taken

Rules can be simple (single condition) or complex (multiple conditions with logical operators like AND, OR).

Git Integration

FinWatch integrates with Git for version-controlled rule management. This means you can:

Store your rules in a Git repository
Track changes to rules over time
Collaborate with your team using pull requests and code reviews
Roll back to previous versions if needed

The Git APIs allow you to:

Status — Check the current status of your Git repository (modified files, uncommitted changes)
Pull — Sync changes from a remote repository
Push — Commit and push your local changes to a remote repository
Clone — Initialize a local repository from a remote one

This integration ensures that your rules are managed like code — with version control, collaboration, and auditability.

API Endpoints

The FinWatch API is organized into three main categories:

Category	Endpoints	Description
Transactions	Inject, Retrieve, Webhook	Send transactions for evaluation and retrieve transaction details
Instructions	List, Get, Delete, Compile & Save	Create and manage monitoring rules
Git	Status, Pull, Push, Clone	Integrate with Git for rule version control

Response Codes

The FinWatch API uses standard HTTP status codes to indicate the result of your request:

Code	Description	What it means
`200 OK`	Request successful	Your request was processed successfully
`201 Created`	Resource created successfully	A new resource (e.g., a rule) was created
`204 No Content`	Resource deleted successfully	The resource was deleted (no content in response)
`400 Bad Request`	Invalid request parameters	Your request had missing or invalid data
`404 Not Found`	Resource not found	The requested resource doesn’t exist
`409 Conflict`	Resource already exists	You tried to create something that already exists (e.g., a rule with the same name)
`500 Internal Server Error`	Server error	Something went wrong on the server side

Always check the status code of your response to ensure your request was successful. If you receive a 4xx or 5xx error, the response body will typically include more details about what went wrong.

Next Steps

Now that you understand the basics, dive deeper into the specific API endpoints:

Transaction APIs — Learn how to inject transactions, retrieve transaction details, and handle webhook events from Blnk
Instruction Management APIs — Create, list, retrieve, and delete monitoring rules
Git Repository APIs — Integrate with Git for version-controlled rule management
Data Models — Understand the detailed structure of transactions, instructions, and other data objects
Error Handling — Learn how to handle errors gracefully in your application

If you’re new to APIs, we recommend starting with the Transaction APIs section to understand how to send transactions to FinWatch. Once you’re comfortable with that, move on to creating rules with the Instruction Management APIs.

​What is FinWatch?

​Base URL

​Quick Start

​1. Inject a Transaction

​2. Create a Monitoring Rule

​3. Retrieve a Transaction

​Authentication

​Core Concepts

​Transactions

​Instructions (Rules)

​Git Integration

​API Endpoints

​Response Codes

​Next Steps