# Watchtower — Sanctions & Watchlist Screening API

Deterministic sanctions & export-control screening for AI agents. Screen names of
people, companies, vessels, and aircraft against: US OFAC (SDN + Consolidated),
UN Security Council, EU Financial Sanctions (FSF), UK OFSI, Canada (SEMA), and US export-control
lists — Commerce/BIS (Entity List, Denied Persons, Unverified, Military End User)
and State Dept (ITAR-Debarred, Nonproliferation). Also screens crypto addresses
against OFAC's sanctioned-address list. ~44,000 designated parties, refreshed daily
from official government sources.

Same query + same list snapshot => byte-identical response, every time.
Every response carries the list snapshot version (content hash) and algorithm version.

## Quickstart (60 seconds, no signup form)

1. Get a key (comes with free trial credit):
   curl -X POST https://watchtower-api.com/v1/keys -H 'Content-Type: application/json' -d '{"note":"my-agent"}'

2. Screen a name ($0.02/call):
   curl -X POST https://watchtower-api.com/v1/screen \
     -H 'Authorization: Bearer YOUR_KEY' -H 'Content-Type: application/json' \
     -d '{"name":"Vladimir Putin"}'

3. Screen a crypto address ($0.01/call):
   curl -X POST https://watchtower-api.com/v1/screen/address \
     -H 'Authorization: Bearer YOUR_KEY' -H 'Content-Type: application/json' \
     -d '{"address":"0x0330070FD38Ec3bB94F58FA55D40368271E9e54A"}'

## Endpoints

- POST /v1/keys — create API key with trial credit. Free.
- POST /v1/screen — {name, threshold?, limit?, types?} → {match, matches[], snapshot_version, algorithm}. $0.02.
- POST /v1/screen/address — {address} → {match, result}. $0.01.
- POST /v1/screen/batch — {names: [up to 500]} → per-name results. $0.015/name (25% off).
- POST /v1/watch — {name, webhook_url, days (1-90)} → monitor a name; your webhook
  gets POSTed whenever its match set changes as sanctions lists update. $0.01/day,
  prepaid. GET /v1/watch lists yours; DELETE /v1/watch/:id cancels.
  watch_changed events include added[] (new matching entries, full records) and
  removed[] (uids no longer matching) so you know exactly what changed. Failed
  webhook deliveries are retried on the next sweep — alerts are never silently dropped.
- GET /v1/entity/:uid — full record (aliases, DOB, nationality, programs) for any
  uid returned by a screen. Free.
- GET /v1/balance — remaining credit. Free.
- POST /v1/topup — Stripe checkout link for credit packs.

## Paying with x402 (no signup needed)

Both /v1/screen endpoints accept x402 v2 payments: call without credentials, read the
402 response's `accepts` array (USDC on Base, eip155:8453), retry with an X-PAYMENT
header. Standard x402 client libraries handle this automatically. Settlement receipt
is returned in the X-PAYMENT-RESPONSE header.
- GET /v1/lists — list versions, source hashes, freshness, pricing. Free.
- GET /openapi.json — machine-readable spec.
- GET /docs — human-readable quickstart + full API reference (HTML).
- POST /mcp — MCP (Model Context Protocol) streamable-HTTP endpoint exposing tools:
  create_api_key, screen_name, screen_crypto_address, get_screening_info.
  Point any MCP client at https://watchtower-api.com/mcp — no auth handshake; keys are tool parameters.

## Matching semantics (algorithm wt-match-2)

- Case-, punctuation-, and diacritic-insensitive; token-order-insensitive.
- Typo-tolerant (Jaro-Winkler + trigram blend).
- Subset detection: "Vladmir Putin" matches "PUTIN, Vladimir Vladimirovich".
- Generic tokens (Inc, Company, Ltd...) carry reduced weight; at least two
  distinctive tokens are required for a subset match.
- threshold (default 0.82): raise to 0.9+ for fewer, stronger matches.
- Deterministic ordering: score desc, then uid asc.

Lists refresh daily from official sources (Treasury/OFAC, UN). Not legal advice;
informational screening only.