Fix KYC issues

.agents/skills/didit-aml-screening/SKILL.md

@@ -0,0 +1,310 @@
+---
+name: didit-aml-screening
+description: >
+  Integrate Didit AML Screening standalone API to screen individuals or companies against
+  global watchlists. Use when the user wants to perform AML checks, screen against sanctions
+  lists, check PEP status, detect adverse media, implement KYC/AML compliance, screen against
+  OFAC/UN/EU watchlists, calculate risk scores, or perform anti-money laundering screening
+  using Didit. Supports 1300+ databases, fuzzy name matching, configurable scoring weights,
+  and continuous monitoring.
+version: 1.1.0
+metadata:
+  openclaw:
+    requires:
+      env:
+        - DIDIT_API_KEY
+    primaryEnv: DIDIT_API_KEY
+    emoji: '🛡️'
+    homepage: https://docs.didit.me
+---
+
+# Didit AML Screening API
+
+## Overview
+
+Screens individuals or companies against 1,300+ global watchlists and high-risk databases in real-time. Uses a two-score system: **Match Score** (identity confidence) and **Risk Score** (threat level).
+
+**Key constraints:**
+
+- `full_name` is the only **required** field
+- Supports `entity_type`: `"person"` (default) or `"company"`
+- Document number acts as a "Golden Key" for definitive matching
+- All weight parameters must sum to 100
+
+**Coverage:** OFAC SDN, UN, EU, HM Treasury, Interpol, FBI, 170+ national sanction lists, PEP Levels 1-4, 50,000+ adverse media sources, financial crime databases.
+
+**Scoring system:**
+
+1. **Match Score** (0-100): Is this the same person? → classifies hits as False Positive or Unreviewed
+2. **Risk Score** (0-100): How risky is this entity? → determines final AML status
+
+**API Reference:** https://docs.didit.me/standalone-apis/aml-screening
+**Feature Guide:** https://docs.didit.me/core-technology/aml-screening/overview
+**Risk Scoring:** https://docs.didit.me/core-technology/aml-screening/aml-risk-score
+
+---
+
+## Authentication
+
+All requests require `x-api-key` header. Get your key from [Didit Business Console](https://business.didit.me) → API & Webhooks, or via programmatic registration (see below).
+
+## Getting Started (No Account Yet?)
+
+If you don't have a Didit API key, create one in 2 API calls:
+
+1. **Register:** `POST https://apx.didit.me/auth/v2/programmatic/register/` with `{"email": "you@gmail.com", "password": "MyStr0ng!Pass"}`
+2. **Check email** for a 6-character OTP code
+3. **Verify:** `POST https://apx.didit.me/auth/v2/programmatic/verify-email/` with `{"email": "you@gmail.com", "code": "A3K9F2"}` → response includes `api_key`
+
+**To add credits:** `GET /v3/billing/balance/` to check, `POST /v3/billing/top-up/` with `{"amount_in_dollars": 50}` for a Stripe checkout link.
+
+See the **didit-verification-management** skill for full platform management (workflows, sessions, users, billing).
+
+---
+
+## Endpoint
+
+```
+POST https://verification.didit.me/v3/aml/
+```
+
+### Headers
+
+| Header         | Value              | Required |
+| -------------- | ------------------ | -------- |
+| `x-api-key`    | Your API key       | **Yes**  |
+| `Content-Type` | `application/json` | **Yes**  |
+
+### Body (JSON)
+
+| Parameter                   | Type    | Required | Default    | Description                                   |
+| --------------------------- | ------- | -------- | ---------- | --------------------------------------------- |
+| `full_name`                 | string  | **Yes**  | —          | Full name of person or entity                 |
+| `date_of_birth`             | string  | No       | —          | DOB in `YYYY-MM-DD` format                    |
+| `nationality`               | string  | No       | —          | ISO country code (alpha-2 or alpha-3)         |
+| `document_number`           | string  | No       | —          | ID document number ("Golden Key")             |
+| `entity_type`               | string  | No       | `"person"` | `"person"` or `"company"`                     |
+| `aml_name_weight`           | integer | No       | `60`       | Name weight in match score (0-100)            |
+| `aml_dob_weight`            | integer | No       | `25`       | DOB weight in match score (0-100)             |
+| `aml_country_weight`        | integer | No       | `15`       | Country weight in match score (0-100)         |
+| `aml_match_score_threshold` | integer | No       | `93`       | Below = False Positive, at/above = Unreviewed |
+| `save_api_request`          | boolean | No       | `true`     | Save in Business Console                      |
+| `vendor_data`               | string  | No       | —          | Your identifier for session tracking          |
+
+### Example
+
+```python
+import requests
+
+response = requests.post(
+    "https://verification.didit.me/v3/aml/",
+    headers={"x-api-key": "YOUR_API_KEY", "Content-Type": "application/json"},
+    json={
+        "full_name": "John Smith",
+        "date_of_birth": "1985-03-15",
+        "nationality": "US",
+        "document_number": "AB1234567",
+        "entity_type": "person",
+    },
+)
+print(response.json())
+```
+
+```typescript
+const response = await fetch('https://verification.didit.me/v3/aml/', {
+  method: 'POST',
+  headers: { 'x-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    full_name: 'John Smith',
+    date_of_birth: '1985-03-15',
+    nationality: 'US',
+  }),
+});
+```
+
+### Response (200 OK)
+
+```json
+{
+  "request_id": "a1b2c3d4-...",
+  "aml": {
+    "status": "Approved",
+    "total_hits": 2,
+    "score": 45.5,
+    "hits": [
+      {
+        "id": "hit-uuid",
+        "caption": "John Smith",
+        "match_score": 85,
+        "risk_score": 45.5,
+        "review_status": "False Positive",
+        "datasets": ["PEP"],
+        "properties": { "name": ["John Smith"], "country": ["US"] },
+        "score_breakdown": {
+          "name_score": 95,
+          "name_weight": 60,
+          "dob_score": 100,
+          "dob_weight": 25,
+          "country_score": 100,
+          "country_weight": 15
+        },
+        "risk_view": {
+          "categories": { "score": 55, "risk_level": "High" },
+          "countries": { "score": 23, "risk_level": "Low" },
+          "crimes": { "score": 0, "risk_level": "Low" }
+        }
+      }
+    ],
+    "screened_data": {
+      "full_name": "John Smith",
+      "date_of_birth": "1985-03-15",
+      "nationality": "US",
+      "document_number": "AB1234567"
+    },
+    "warnings": []
+  }
+}
+```
+
+---
+
+## Match Score System
+
+**Formula:** `(Name × W1) + (DOB × W2) + (Country × W3)`
+
+| Component | Default Weight | Algorithm                                                            |
+| --------- | -------------- | -------------------------------------------------------------------- |
+| Name      | 60%            | RapidFuzz WRatio — handles typos, word order, middle name variations |
+| DOB       | 25%            | Exact=100%, Year-only=100%, Same year diff date=50%, Mismatch=-100%  |
+| Country   | 15%            | Exact=100%, Mismatch=-50%, Missing=0%. Auto-converts ISO codes       |
+
+**Document Number "Golden Key":**
+
+| Scenario                      | Effect                    |
+| ----------------------------- | ------------------------- |
+| Same type, same value         | Override score to **100** |
+| Different type or one missing | Keep base score (neutral) |
+| Same type, different value    | **-50 point penalty**     |
+
+**Classification:** Score < threshold (default 93) → **False Positive**. Score >= threshold → **Unreviewed**.
+
+> When data is missing, remaining weights are re-normalized. E.g., name-only → name weight becomes 100%.
+
+---
+
+## Risk Score System
+
+**Formula:** `(Country × 0.30) + (Category × 0.50) + (Criminal × 0.20)`
+
+**Final AML Status (from highest risk score among non-FP hits):**
+
+| Highest Risk Score  | Status        |
+| ------------------- | ------------- |
+| Below 80 (default)  | **Approved**  |
+| Between 80-100      | **In Review** |
+| Above 100           | **Declined**  |
+| All False Positives | **Approved**  |
+
+**Category scores (50% weight):**
+
+| Category                     | Score |
+| ---------------------------- | ----- |
+| Sanctions / PEP Level 1      | 100   |
+| Warnings & Regulatory        | 95    |
+| PEP Level 2 / Insolvency     | 80    |
+| Adverse Media                | 60    |
+| PEP Level 4 / Businessperson | 55    |
+
+---
+
+## Status Values & Handling
+
+| Status          | Meaning                                       | Action                            |
+| --------------- | --------------------------------------------- | --------------------------------- |
+| `"Approved"`    | No significant matches or all False Positives | Safe to proceed                   |
+| `"In Review"`   | Matches found with moderate risk              | Manual compliance review needed   |
+| `"Rejected"`    | High-risk matches confirmed                   | Block or escalate per your policy |
+| `"Not Started"` | Screening not yet performed                   | Check for missing data            |
+
+### Error Responses
+
+| Code  | Meaning              | Action                                  |
+| ----- | -------------------- | --------------------------------------- |
+| `400` | Invalid request body | Check `full_name` and parameter formats |
+| `401` | Invalid API key      | Verify `x-api-key` header               |
+| `403` | Insufficient credits | Check credits in Business Console       |
+
+---
+
+## Warning Tags
+
+| Tag                               | Description                                                            |
+| --------------------------------- | ---------------------------------------------------------------------- |
+| `POSSIBLE_MATCH_FOUND`            | Potential watchlist matches requiring review                           |
+| `COULD_NOT_PERFORM_AML_SCREENING` | Missing KYC data. Provide full name, DOB, nationality, document number |
+
+---
+
+## Response Field Reference
+
+### Hit Object
+
+| Field                      | Type    | Description                                                               |
+| -------------------------- | ------- | ------------------------------------------------------------------------- |
+| `match_score`              | integer | 0-100 identity confidence score                                           |
+| `risk_score`               | float   | 0-100 threat level score                                                  |
+| `review_status`            | string  | `"False Positive"`, `"Unreviewed"`, `"Confirmed Match"`, `"Inconclusive"` |
+| `datasets`                 | array   | e.g. `["Sanctions"]`, `["PEP"]`, `["Adverse Media"]`                      |
+| `pep_matches`              | array   | PEP match details                                                         |
+| `sanction_matches`         | array   | Sanction match details                                                    |
+| `adverse_media_matches`    | array   | `{headline, summary, source_url, sentiment_score, adverse_keywords}`      |
+| `linked_entities`          | array   | Related persons/entities                                                  |
+| `first_seen` / `last_seen` | string  | ISO 8601 timestamps                                                       |
+
+**Adverse media sentiment:** `-1` = slightly negative, `-2` = moderately, `-3` = highly negative.
+
+---
+
+## Continuous Monitoring
+
+Available on **Pro plan**. Automatically included for all AML-screened sessions.
+
+- **Daily automated re-screening** against updated watchlists
+- New hits → session status updated to "In Review" or "Declined" based on thresholds
+- **Real-time webhook notifications** on status changes
+- Zero additional integration — uses same thresholds from workflow config
+
+---
+
+## Common Workflows
+
+### Basic AML Check
+
+```
+1. POST /v3/aml/ → {"full_name": "John Smith", "nationality": "US"}
+2. If "Approved" → no significant watchlist matches
+   If "In Review" → review hits[].datasets, hits[].risk_view for details
+   If "Rejected" → block user, check hits for sanctions/PEP details
+```
+
+### Comprehensive KYC + AML
+
+```
+1. POST /v3/id-verification/ → extract name, DOB, nationality, document number
+2. POST /v3/aml/ → screen extracted data with all fields populated
+3. More data = higher match accuracy = fewer false positives
+```
+
+---
+
+## Utility Scripts
+
+**screen_aml.py**: Screen against AML watchlists from the command line.
+
+```bash
+# Requires: pip install requests
+export DIDIT_API_KEY="your_api_key"
+python scripts/screen_aml.py --name "John Smith"
+python scripts/screen_aml.py --name "John Smith" --dob 1985-03-15 --nationality US
+python scripts/screen_aml.py --name "Acme Corp" --entity-type company
+```

.agents/skills/didit-aml-screening/scripts/screen_aml.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""Didit AML Screening - Screen individuals or companies against global watchlists.
+
+Usage:
+    python scripts/screen_aml.py --name "John Smith"
+    python scripts/screen_aml.py --name "John Smith" --dob 1985-03-15 --nationality US
+
+Environment:
+    DIDIT_API_KEY - Required. Your Didit API key.
+
+Examples:
+    python scripts/screen_aml.py --name "John Smith"
+    python scripts/screen_aml.py --name "Acme Corp" --entity-type company
+    python scripts/screen_aml.py --name "Maria Garcia" --dob 1990-01-01 --nationality ESP --doc-number X1234567
+"""
+import argparse
+import json
+import os
+import sys
+
+import requests
+
+ENDPOINT = "https://verification.didit.me/v3/aml/"
+
+
+def get_api_key() -> str:
+    api_key = os.environ.get("DIDIT_API_KEY")
+    if not api_key:
+        print("Error: DIDIT_API_KEY environment variable is not set.", file=sys.stderr)
+        sys.exit(1)
+    return api_key
+
+
+def screen_aml(full_name: str, date_of_birth: str = None, nationality: str = None,
+               document_number: str = None, entity_type: str = "person",
+               threshold: int = None, vendor_data: str = None) -> dict:
+    api_key = get_api_key()
+    payload = {"full_name": full_name, "entity_type": entity_type}
+    if date_of_birth:
+        payload["date_of_birth"] = date_of_birth
+    if nationality:
+        payload["nationality"] = nationality
+    if document_number:
+        payload["document_number"] = document_number
+    if threshold is not None:
+        payload["aml_match_score_threshold"] = threshold
+    if vendor_data:
+        payload["vendor_data"] = vendor_data
+    r = requests.post(ENDPOINT,
+                      headers={"x-api-key": api_key, "Content-Type": "application/json"},
+                      json=payload, timeout=60)
+    if r.status_code not in (200, 201):
+        print(f"Error {r.status_code}: {r.text}", file=sys.stderr)
+        sys.exit(1)
+    return r.json()
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Screen against AML watchlists via Didit")
+    parser.add_argument("--name", required=True, help="Full name of person or entity")
+    parser.add_argument("--dob", help="Date of birth (YYYY-MM-DD)")
+    parser.add_argument("--nationality", help="Country code (alpha-2 or alpha-3)")
+    parser.add_argument("--doc-number", help="Document number")
+    parser.add_argument("--entity-type", default="person", choices=["person", "company"],
+                        help="Entity type (default: person)")
+    parser.add_argument("--threshold", type=int, help="Match score threshold (0-100)")
+    parser.add_argument("--vendor-data", help="Your identifier for tracking")
+    args = parser.parse_args()
+
+    result = screen_aml(args.name, args.dob, args.nationality, args.doc_number,
+                        args.entity_type, args.threshold, args.vendor_data)
+    print(json.dumps(result, indent=2))
+
+    aml = result.get("aml", {})
+    status = aml.get("status", "Unknown")
+    total_hits = aml.get("total_hits", 0)
+    print(f"\n--- Status: {status} | Total hits: {total_hits} ---")
+    for hit in aml.get("hits", [])[:5]:
+        print(f"  {hit.get('match_score', '?')}% — {hit.get('name', '?')} "
+              f"[{', '.join(hit.get('categories', []))}]")
+
+
+if __name__ == "__main__":
+    main()