Project Documentation · API Endpoints · API Guide · Community · Blog

moov-io/watchman

Moov's mission is to give developers an easy way to create and integrate bank processing into their own software products. Our open source projects are each focused on solving a single responsibility in financial services and designed around performance, scalability, and ease of use.

What is Watchman?

Moov Watchman is a high-performance sanctions screening and compliance tool that helps businesses meet their regulatory obligations. It provides an HTTP server, Go library, and secure Model Context Protocol (MCP) server for searching against multiple global sanctions and screening lists. Watchman offers a unified model for entities and queries for humans and agents.

Key Features

• Geocoding: Using one of the supported providers.
• Senzing Support: Import data files in senzing format and get search responses as senzing entities.
• Comprehensive Coverage: Integrates multiple global watchlists in one unified system
• High-Performance Search: Optimized for speed and accuracy using advanced matching algorithms
• Flexible Integration: HTTP API and Go library for easy integration into your systems
• Automated Updates: Regular refreshes of watchlist data to ensure compliance
• Model Context Protocol: Integrate AI agents into screening workflows with secure MCP and agentpass.

Included Lists

Watchman integrates the following lists to help you maintain global compliance. Use the env variable INCLUDED_LISTS or config file to customize which lists are loaded.

Agents

Watchman provides an HTTP /mcp endpoint with full Model Context Protocol (MCP) support, allowing agents to search the loaded lists. The endpoint is protected by MCPS, which cryptographically verifies agent chains and calls at the point of screening. Untrusted requests are automatically blocked, and every request is proven tamper-resistant through cryptographic attestation.

Only agents that can prove their identity are permitted to screen entities, verify transactions, or initiate payments.

Check out the live demo to see seamless agent onboarding, verification, and screening in action.

Project status

Moov Watchman is actively used in multiple production environments. Please star the project if you are interested in its progress. If you have layers above Watchman to simplify tasks, perform business operations, or found bugs we would appreciate an issue or pull request. Thanks!

Usage

The Watchman project implements an HTTP server, Go library, and experimental Model Context Protocol (MCP) server for searching against Watchman.

Government lists are downloaded (and refreshed), parsed, prepared, normalized, and indexed in-memory. Searches operate concurrently and do not require an external database or connection.

Docker

We publish a public Docker image moov/watchman from Docker Hub or use this repository. No configuration is required to serve on :8084. We also have Docker images for OpenShift published as quay.io/moov/watchman. Lastly, we offer a moov/watchman:v2-static Docker image with files from 2019. This image can be useful for faster local testing or consistent results.

Start the Docker image using a tag:

docker run -p 8084:8084 moov/watchman

Run a search for an individual or business:

curl -s "http://localhost:8084/v2/search?name=Nicolas+Maduro&type=person&limit=1&minMatch=0.75" | jq .

{
  "entities": [
    {
      "name": "Nicolas MADURO MOROS",
      "entityType": "person",
      "sourceList": "us_ofac",
      "sourceID": "22790",
      "person": {
        "name": "Nicolas MADURO MOROS",
        "altNames": null,
        "gender": "male",
        "birthDate": "1962-11-23T00:00:00Z",
        "deathDate": null,
        "titles": [
          "President of the Bolivarian Republic of Venezuela"
        ],
        "governmentIDs": [
          {
            "type": "cedula",
            "country": "Venezuela",
            "identifier": "5892464"
          }
        ]
      },
      "business": null,
      "organization": null,
      "aircraft": null,
      "vessel": null,
      "contact": {
        "emailAddresses": null,
        "phoneNumbers": null,
        "faxNumbers": null,
        "websites": null
      },
      "addresses": null,
      "cryptoAddresses": null,
      "affiliations": null,
      "sanctionsInfo": null,
      "historicalInfo": null,
      "sourceData": {
        "entityID": "22790",
        "sdnName": "MADURO MOROS, Nicolas",
        "sdnType": "individual",
        "program": [
          "VENEZUELA",
          "IRAN-CON-ARMS-EO"
        ],
        "title": "President of the Bolivarian Republic of Venezuela",
        "callSign": "",
        "vesselType": "",
        "tonnage": "",
        "grossRegisteredTonnage": "",
        "vesselFlag": "",
        "vesselOwner": "",
        "remarks": "DOB 23 Nov 1962; POB Caracas, Venezuela; citizen Venezuela; Gender Male; Cedula No. 5892464 (Venezuela); President of the Bolivarian Republic of Venezuela."
      },
      "match": 0.7784062500000001
    }
  ]
}

Data persistence

By design, Watchman does not persist (save) any data about the search queries or lists pulled from external sources. Watchman can store ingested files (the individual records) in a MySQL or PostgreSQL database for concurrent access. External lists that are downloaded on startup (and refreshed periodically) are only kept in memory. No encryption of data in-memory is performed.

Configuration

Watchman recommends file-based configuration but supports environmental variable options.

FAQ

Reporting hits to OFAC

OFAC requires reporting of positive hits and has a voluntary self-disclosure portal. Work with your Financial Institution for complete details.

Useful resources

• OFAC Sanctions Search Page
• Subscribe for OFAC email updates
• When should I call the OFAC Hotline?
• BIS Denied Persons List with Denied US Export Privileges (DPL)
• BIS Entity List
• Sectoral Sanctions Identifications (SSI)
• US Sanctions Search FAQ

Getting help

If you find a security issue please contact us at security@moov.io.

Supported and tested platforms

• 64-bit Linux (Ubuntu, Debian), macOS, and Windows

Contributing

Yes please! Checkout our issues for first time contributors for something to help out with.

Building Watchman's source code follows standard Go commands. You can use make build to compile the code and make check to run linters and tests.

Run make install to setup gopostal / libpostal for Watchman.

Related projects

As part of Moov's initiative to offer open source fintech infrastructure, we have a large collection of active projects you may find useful:

• Moov Fed implements utility services for searching the United States Federal Reserve System such as ABA routing numbers, financial institution name lookup, and FedACH and Fedwire routing information.

• Moov Image Cash Letter implements Image Cash Letter (ICL) files used for Check21, X.9 or check truncation files for exchange and remote deposit in the U.S.

• Moov Wire implements an interface to write files for the Fedwire Funds Service, a real-time gross settlement funds transfer system operated by the United States Federal Reserve Banks.

• Moov ACH provides ACH file generation and parsing, supporting all Standard Entry Codes for the primary method of money movement throughout the United States.

• Moov Metro 2 provides a way to easily read, create, and validate Metro 2 format, which is used for consumer credit history reporting by the United States credit bureaus.

License

Apache License 2.0 - See LICENSE for details.