# 📖 REST & WebSocket API Reference Specification Comprehensive endpoint blueprints, request/response JSON schemas, authentication protocols, and streaming telemetry interfaces for the Collaborative Financial Crime Intelligence Platform (**CF-Intelligence**). --- ## 📌 Architecture & Protocol Conventions All CF-Intelligence API endpoints follow strict Clean Architecture, OpenAPI 3.1.0, and Zero-Trust principles: - **Base URL (Local Gateway):** http://localhost:8000 (or http://localhost via Nginx Reverse Proxy) - **Base URL (Interactive UI):** http://localhost:3000 (Vite SPA) - **Interactive Documentation:** - Swagger UI: http://localhost:8000/docs - ReDoc Portal: http://localhost:8000/redoc - Scalar Interactive API Reference: http://localhost:8000/developer - **Authentication & Tenant Isolation:** - Bearer JWT tokens (Authorization: Bearer ) validated via RFC 7519 standard. - Multi-tenant cryptographic isolation via mandatory X-Tenant-ID header. - **Distributed Tracing & Context Propagation:** - W3C Trace Context headers ( raceparent, racestate) propagated through all API gateways and asynchronous Celery/Kafka tasks. - **Standardized Error Responses:** - RFC 7807 Problem Details (pplication/problem+json) with deterministic error codes, validation error vectors, and timestamped audit tracking. - **Rate Limiting & Abuse Defense:** - Sliding-window rate limiting enforced by Redis Sentinel and slowapi (returns HTTP 429 Too Many Requests with Retry-After). --- ## 📑 API Endpoint Directory (20 Endpoints) | # | Endpoint | Method | Category | Description | | :--- | :--- | :---: | :--- | :--- | | **18.1** | /api/v1/score-transaction | POST | Real-Time Scoring | Normalized transaction fraud risk scoring & feature attributions | | **18.2** | /api/v1/auth/login | POST | Authentication | Enterprise JWT session issuance & multi-factor verification | | **18.3** | /health, /health/ready, /ready, /health/live, /live | GET | System Probes | Deep database, cache, and Kubernetes liveness & readiness probes | | **18.4** | /ws/telemetry | WS | Telemetry | Real-time multi-bank consortium WebSocket metrics broadcast | | **18.5** | /developer | GET | Developer Portal | Interactive Scalar API Gateway documentation | | **18.6** | /api/v1/scenarios/inject-attack | POST | Adversarial Simulation | Chaos & poisoning attack injection (label flipping, sign inversion) | | **18.7** | /api/v1/data/ingest-dataset | POST | Data Ingestion | Multi-dataset ingestion (PaySim, IEEE-CIS, Elliptic) & contract checks | | **18.8** | /api/v1/banks/scoring-volume | GET | Consortium Analytics | 24-hour historical consortium transaction scoring volume | | **18.9** | /api/v1/fl/events | GET | FL Engine | Federated training round convergence & Server-Sent Events stream | | **18.10** | /api/v1/regulatory/export-sar | POST | Regulatory & Audit | Automated FinCEN SAR XML generation & cryptographic key rotation | | **18.11** | /api/v1/cases/{id}/label-feedback | POST | Human-in-the-Loop | Analyst verdict feedback loop & continuous retraining store | | **18.12** | /api/v1/bridge/message | POST | FININT Bridge | Inter-bank end-to-end encrypted FININT messaging protocol | | **18.13** | /api/v1/recalls/initiate | POST | SEPA Instant | Real-time SEPA Instant Payment Recall (camt.056) automation | | **18.14** | /api/v1/screening/screen | POST | Sanctions / PEP | Real-time fuzzy MinHash LSH screening against OFAC & EU watchlists | | **18.15** | /api/v1/regulatory/export-amla | POST | EU AMLA & goAML | European FIU & UNODC goAML 4.0 XML regulatory reporting | | **18.16** | /api/v2/*, /api/v1/* | POST | Drop-in Adapter | Enterprise AML drop-in OpenAPI adapter & webhook gateway | | **18.17** | /api/v1/ubo/analyze-graph | POST | Graph Intelligence | Cross-border corporate UBO & heterogeneous GraphSAGE analysis | | **18.18** | /api/v1/scenarios/european-aml/evaluate | POST | European AML Rules | Hybrid deterministic FATF rule evaluation & scenario library | | **18.19** | /api/v1/operations/asset-recovery/hold | POST | Asset Recovery | Collaborative FININT operational hub & multi-bank asset freeze | | **18.20** | /api/v1/coordinator/* | GET/POST | FL Coordinator | Bank node registration, telemetry, and hyperparameter negotiation | --- ## 18. API Endpoint Blueprints & JSON Schemas ### 18.1 Real-Time Transaction Risk Scoring **Normalized Transaction Scoring Request (`POST /api/v1/score-transaction`):** ```json { "transaction_id": "txn_88492049281", "account_id": "DE89370400440532013000", "amount": 250000.0, "currency": "EUR", "merchant_id": "crypto_exchange_01", "country": "US", "device_id": "dev_fp_993810a" } ``` **Normalized Transaction Scoring Response (HTTP 200 OK):** ```json { "risk_score": 895, "risk_level": "HIGH", "decision": "BLOCK", "model_version": "v2.4.1", "explanations": [ {"feature": "velocity", "contribution": 0.38}, {"feature": "transaction_amount", "contribution": 0.29}, {"feature": "merchant_risk_score", "contribution": 0.18} ], "related_entities": [ {"entity_type": "merchant", "risk": "HIGH"} ], "latency_ms": 14.2 } ``` > [!NOTE] > **Real SHAP Attribution Computation:** The feature contribution values in the example above illustrate the response schema contract. At serving time, explanations are computed dynamically by `ExplainabilityService.compute_shap_values()` ([README Section 9.2](../README.md#92-model-explainability--counterfactual-search-explainability_servicepy--risk_enginepy)) using real `shap.KernelExplainer` against the PyTorch serving neural network (`FraudDetectionModel`), guaranteeing the mathematical Shapley local accuracy property ($\sum \phi_i + \text{base value} = f(\mathbf{x})$) within floating point tolerance. **Full-Feature Inference Request (`POST /api/v1/predict`):** ```json { "transaction_amount": 250000.0, "merchant_category": "crypto", "country_code": "US", "device_type": "web_browser", "velocity": 12.5, "hour_of_day": 3, "merchant_risk_score": 0.85, "customer_history_score": 0.12, "chargeback_count": 4, "account_age_days": 14, "bank_id": "bank_alpha" } ``` **Full-Feature Inference Response (HTTP 200 OK):** ```json { "fraud_probability": 0.942, "risk_score": 895.4, "is_fraud_suspected": true, "risk_level": "CRITICAL", "policy_action": "BLOCK", "triggered_rules": [ "HIGH_VELOCITY_SUSPICIOUS_MERCHANT", "NEW_ACCOUNT_HIGH_VALUE_CRYPTO" ], "breakdown": [ { "signal_name": "S_velocity", "weight": 0.20, "raw_value": 12.5, "normalized_score": 980.0, "explanation": "High velocity transfer burst within 1 hour" }, { "signal_name": "S_graph", "weight": 0.15, "raw_value": 0.88, "normalized_score": 920.0, "explanation": "GraphSAGE embedding anomaly detected across entity cluster" } ] } ``` ### 18.2 Enterprise Authentication & Session Management **Login Request (`POST /api/v1/auth/login`):** ```json { "username": "investigator_alpha", "password": "CorrectHorseBatteryStaple123!" } ``` **Login Response (HTTP 200 OK):** ```json { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "bearer", "expires_in": 900, "user": { "username": "investigator_alpha", "bank_id": "bank_alpha", "roles": ["investigator", "analyst"] } } ``` **Token Refresh Request (`POST /api/v1/auth/refresh`):** ```json { "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } ``` **Lockout Status Check (`GET /api/v1/auth/lockout-status?username=investigator_alpha`):** ```json { "username": "investigator_alpha", "client_ip": "198.51.100.42", "is_locked_out": false, "remaining_lockout_seconds": 0, "user_failure_count": 0, "ip_failure_count": 0 } ``` ### 18.3 Enterprise Connector Diagnostics & Live Probes **List Connector Health Status (`GET /api/v1/diagnostics/connectors`):** ```json { "status": "healthy", "total_connectors": 7, "healthy_connectors": 7, "degraded_connectors": 0, "unhealthy_connectors": 0, "connectors": [ { "id": "kafka_stream", "name": "Apache Kafka (Distributed Event Bus)", "category": "STREAMING", "status": "HEALTHY", "endpoint": "kafka.internal:9092", "latency_ms": 4.2, "last_checked": "2026-09-02T14:35:00Z" }, { "id": "vault_pki", "name": "HashiCorp Vault (PKI & Secrets)", "category": "SECURITY", "status": "HEALTHY", "endpoint": "https://vault.internal:8200", "latency_ms": 6.8, "last_checked": "2026-09-02T14:35:00Z" } ] } ``` **Execute On-Demand Connector Ping Probe (`POST /api/v1/diagnostics/test-connector`):** ```json { "connector_id": "splunk_hec" } ``` **Probe Response (HTTP 200 OK):** ```json { "connector_id": "splunk_hec", "status": "HEALTHY", "latency_ms": 11.4, "handshake_trace": [ "DNS resolution: splunk.internal -> 10.200.4.15", "TCP SYN/ACK established on port 8088", "TLS 1.3 handshake: ECDHE-RSA-AES256-GCM-SHA384", "HEC Token validation probe: HTTP 200 OK (Channel active)" ], "timestamp": "2026-09-02T14:35:10Z" } ``` ### 18.4 Real-Time WebSocket Telemetry Stream **Connection Endpoint:** `ws://localhost:8000/ws/telemetry` (or `wss://...` in production) **Inbound Client Subscription Message:** ```json { "action": "subscribe", "channels": ["transactions", "alerts", "heartbeat"] } ``` **Outbound Real-Time Fraud Alert Event Broadcast:** ```json { "type": "FRAUD_ALERT", "transaction_id": "txn_live_994821", "bank_id": "bank_alpha", "amount": 250000.0, "currency": "EUR", "risk_score": 942, "decision": "BLOCK_AND_ESCALATE", "reason": "Velocity surge detected across 3 consortium nodes within 90 seconds", "timestamp": "2026-09-02T14:35:15Z" } ``` ### 18.5 Interactive Developer Portal & Scalar API Gateway - **Dark-Themed Scalar Gateway:** `GET /scalar` (Renders modern `@scalar/api-reference` targeting `/openapi.json`). - **Interactive Multi-Language SDK Portal:** Route `/developer` and `/api-docs` provides client generator for **cURL**, **Python (httpx)**, **Node.js (axios)**, **Java (OkHttp)**, and **Go (net/http)** with live in-browser execution runner. - **OpenAPI 3.1 JSON Specification:** Available via `GET /openapi.json` or exported directly via the Developer Portal UI. ### 18.6 Interactive Chaos & Adversarial Attack Simulation (`POST /api/v1/scenarios/inject-attack`) **Attack Injection Request:** ```json { "attack_type": "byzantine_poisoning", "adversary_bank": "bank_gamma", "target_bank": "bank_alpha", "intensity_rate": 500, "defense_strategy": "krum" } ``` **Attack Execution Response (HTTP 200 OK):** ```json { "attack_id": "ATK-BYZ-9941", "attack_type": "byzantine_poisoning", "status": "quarantined", "defense_activated": "Krum Robust Byzantine Aggregation", "adversary_quarantined": "bank_gamma", "euclidean_distance": 48.24, "distance_threshold": 14.10, "packets_blocked": 500, "mitigation_latency_ms": 3.8, "auc_protected": 0.9412, "auc_compromised_baseline": 0.5218, "log_entry": "Byzantine poisoned gradient from bank_gamma rejected by Krum Robust Byzantine Aggregation (dist 48.2 > threshold 14.1). Model AUC preserved at 0.9412." } ``` *Note: `auc_protected` and `auc_compromised_baseline` in this endpoint represent continuous simulated demo proxy metrics for live operator HUD feedback and are explicitly tagged as simulated in the schema and console UI.* ### 18.7 Real Dataset Ingestion & Great Expectations Contract Gating **1. Validate Preview & Schema Auto-Detection (`POST /api/v1/datasets/validate-preview`):** ```json { "file_name": "corporate_wires_q3.csv", "content": "timestamp,amount,src,dst,channel,is_fraud\n2026-09-01T08:00:00Z,12500.50,acc_101,acc_902,SWIFT,0\n...", "delimiter": "," } ``` **Preview Response (HTTP 200 OK):** ```json { "inferred_columns": [ {"source_col": "timestamp", "target_signal": "timestamp", "confidence": 0.98, "inferred_type": "datetime"}, {"source_col": "amount", "target_signal": "transaction_amount", "confidence": 0.99, "inferred_type": "float"}, {"source_col": "src", "target_signal": "source_account_id", "confidence": 0.95, "inferred_type": "string"}, {"source_col": "dst", "target_signal": "destination_account_id", "confidence": 0.95, "inferred_type": "string"}, {"source_col": "channel", "target_signal": "channel_type", "confidence": 0.92, "inferred_type": "string"}, {"source_col": "is_fraud", "target_signal": "is_fraud", "confidence": 1.0, "inferred_type": "integer"} ], "row_count": 5000, "column_count": 6, "sample_rows": [], "pii_detected": false } ``` **2. Great Expectations Contract Audit (`POST /api/v1/datasets/contract-audit`):** ```json { "file_name": "corporate_wires_q3.csv", "column_mappings": [ {"source_col": "amount", "target_signal": "transaction_amount"}, {"source_col": "src", "target_signal": "source_account_id"}, {"source_col": "is_fraud", "target_signal": "is_fraud"} ], "rows": [] } ``` **Audit Scorecard Response (HTTP 200 OK):** ```json { "passed": true, "total_checks": 12, "passed_checks": 12, "failed_checks": 0, "checks": [ {"check_name": "expect_column_values_to_not_be_null: amount", "status": "passed"}, {"check_name": "expect_column_values_to_be_between: amount [0.01, 10000000.0]", "status": "passed"}, {"check_name": "expect_column_values_to_be_in_set: channel_type", "status": "passed"} ], "quarantined_rows_count": 0, "dirichlet_alpha_estimate": 0.524, "ks_drift_score": 0.024 } ``` **3. Consortium Enrollment (`POST /api/v1/datasets/consortium-enroll`):** ```json { "dataset_name": "Bank_Alpha_Q3_Wires", "target_bank": "bank_alpha", "partition_strategy": "append_partition", "row_count": 5000, "dirichlet_alpha": 0.524 } ``` ### 18.8 24-Hour Consortium Transaction Scoring Volume (`GET /api/v1/banks/scoring-volume`) Aggregates empirical hourly transaction velocity and volume across all onboarded consortium institutions for operational throughput monitoring: **Request (`GET /api/v1/banks/scoring-volume`):** ```http GET /api/v1/banks/scoring-volume HTTP/1.1 Host: api.cfi-platform.org Authorization: Bearer ``` **Response (HTTP 200 OK):** ```json [ {"time": "00:00", "volume": 1420}, {"time": "01:00", "volume": 890}, {"time": "02:00", "volume": 612}, {"time": "03:00", "volume": 480}, {"time": "12:00", "volume": 8920}, {"time": "14:00", "volume": 9410}, {"time": "23:00", "volume": 2150} ] ``` ### 18.9 Federated Training Convergence & Real-Time Event Streaming **1. Query Training Round Convergence (`GET /api/v1/training/rounds/{simulation_id}`):** ```json [ { "round_number": 1, "total_rounds": 5, "global_loss": 0.5412, "auc": 0.8641, "per_bank_auc": { "bank_a": 0.8812, "bank_b": 0.8540, "bank_c": 0.8571 }, "per_bank_loss": { "bank_a": 0.5210, "bank_b": 0.5580, "bank_c": 0.5446 }, "participating_banks": ["bank_a", "bank_b", "bank_c"], "dropped_banks": [], "duration_ms": 1420 } ] ``` **2. Real-Time Training Event WebSocket Stream (`WS /api/v1/training/ws/{simulation_id}`):** Publishes real-time training iteration progress broadcast via internal Redis Pub/Sub (`training:{simulation_id}` and `training:live_prod_v2`): ```json { "event_type": "round_complete", "data": { "round": 3, "total": 5, "loss": 0.2841, "auc": 0.9412, "per_bank_auc": {"bank_a": 0.951, "bank_b": 0.932, "bank_c": 0.940}, "participants": ["bank_a", "bank_b", "bank_c"], "duration_ms": 1380 } } ``` ### 18.10 Regulatory SAR Export & Key Rotation Cron Endpoints > **Regulatory Simulation Notice:** > Generates schema-validated FinCEN BSA XML Schema 2.0 and UNODC goAML 4.0 electronic filing dossier prototypes for internal case investigation and audit readiness. The platform does **not** transmit live filings to statutory FinCEN BSA E-Filing or European FIU production portals (which require federal banking charter accreditations and dedicated government VPN leased lines). **1. Case SAR FinCEN XML Export (`POST /api/v1/cases/export/fincen-xml`):** Compiles confirmed fraud cases into schema-compliant FinCEN BSA XML Schema 2.0 electronic dossier prototypes: *Request (`POST /api/v1/cases/export/fincen-xml`):* ```json { "case_id": "CASE-2026-9941" } ``` *Response (HTTP 200 OK):* ```json { "status": "FILED", "submission_id": "SAR-XML-2026-9941-A8F2", "case_id": "CASE-2026-9941", "xml": "\n\n Bank Alpha (Synthetic Retail Node)\n Cross-Bank Velocity Surge\n", "timestamp": "2026-09-06T12:00:00Z" } ``` **2. Scheduled Key Rotation Trigger (`POST /v1/cron/rotate-keys`):** Triggered by Kubernetes CronJobs or cloud event schedulers to rotate per-tenant KMS envelope keys: *Request (`POST /v1/cron/rotate-keys`):* ```http POST /v1/cron/rotate-keys HTTP/1.1 Host: api.cfi-platform.org Authorization: Bearer Content-Type: application/json { "tenant_id": "bank_a", "keep_last_n": 2 } ``` *Response (HTTP 200 OK):* ```json { "status": "SUCCESS", "tenant_id": "bank_a", "active_version": 2, "retired_versions": [1], "reencrypted_records_count": 450, "timestamp_iso": "2026-09-06T00:00:00Z" } ``` ### 18.11 Continuous Human-in-the-Loop Feedback & Retraining Ground-Truth Store Connects investigator case determinations directly back to tenant-isolated retraining buffers for continuous federated model fine-tuning: **1. Ingest Analyst Ground-Truth Determination (`POST /api/v1/feedback/ingest`):** ```json { "tenant_id": "bank_alpha", "alert_id": "alt_2001", "determination": "CONFIRMED_FRAUD", "priority": 3, "weight": 2.0, "notes": "Confirmed syndicate structuring across 3 mule accounts" } ``` *Response (HTTP 201 Created):* ```json { "status": "success", "item": { "transaction_id_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "label": "CONFIRMED_FRAUD", "weight": 2.0, "priority": 3, "consumed_for_retraining": false, "recorded_at": "2026-09-16T12:00:00Z" } } ``` **2. Sample Prioritized, Stratified Retraining Batch (`POST /api/v1/feedback/retraining-batch`):** ```json { "tenant_id": "bank_alpha", "batch_size": 32, "stratified": true, "mark_consumed": true } ``` *Response (HTTP 200 OK):* ```json { "tenant_id": "bank_alpha", "batch_size": 32, "items": [], "fraud_count": 16, "false_positive_count": 16, "mean_priority": 2.45 } ``` **3. Compute Differential-Privacy-Protected Gradient Update (`POST /api/v1/feedback/dp-gradient`):** ```json { "tenant_id": "bank_alpha", "epsilon": 1.0, "delta": 1e-5, "clip_norm": 1.0 } ``` *Response (HTTP 200 OK):* ```json { "tenant_id": "bank_alpha", "delta_weights": [0.03512, 0.07184, 0.10621, 0.14289], "sample_count": 32, "epsilon": 1.0, "delta": 1e-05, "sigma": 4.84379 } ``` ### 18.12 Inter-Bank Encrypted FININT Messaging API (`/api/v1/bridge/*`) Enables compliance officers to exchange end-to-end encrypted FININT case tickets and evidentiary payloads across consortium institutions: **1. Create Encrypted Inter-Bank Ticket (`POST /api/v1/bridge/cases`):** ```json { "originating_bank_id": "bank_alpha", "recipient_bank_id": "bank_beta", "case_id": "CASE-EU-2026-0841", "request_type": "MULE_ACCOUNT_INQUIRY", "urgency": "URGENT", "subject_identifier": "DE89370400440532013000", "evidence_payload": "Confirmed rapid layering across 4 intermediary accounts within 180 seconds. Total outbound: EUR 145,000.", "recipient_public_key_hex": "5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b" } ``` *Response (HTTP 201 Created):* ```json { "ticket_id": "FININT-2026-A1B2C3D4", "status": "SUBMITTED", "originating_bank_id": "bank_alpha", "recipient_bank_id": "bank_beta", "encrypted_payload_b64": "v1:G4k9...:AQID...:ZGF0YQ==", "evidence_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "sla_deadline_iso": "2026-09-22T20:00:00Z", "audit_chain_block_hash": "8f3b2a1c0d9e...f7a6b" } ``` **2. Verify Immutable Audit Chain (`GET /api/v1/bridge/cases/{ticket_id}/audit-trail`):** ```json { "ticket_id": "FININT-2026-A1B2C3D4", "chain_valid": true, "block_count": 3, "blocks": [ {"index": 0, "event": "TICKET_CREATED", "status": "SUBMITTED", "block_hash": "8f3b2a..."}, {"index": 1, "event": "STATUS_TRANSITION", "status": "IN_REVIEW", "block_hash": "c4d5e6..."}, {"index": 2, "event": "RESPONSE_ATTACHED", "status": "RESPONDED", "block_hash": "1a2b3c..."} ] } ``` ### 18.13 Real-Time SEPA Instant Payment Recall API (`/api/v1/recalls/*`) Automates European Payments Council (EPC) SEPA Instant Credit Transfer payment recall workflows (`camt.056` / `camt.029`): **1. Initiate Fraud Recall (`POST /api/v1/recalls/initiate`):** ```json { "original_transaction_id": "TX-SEPA-2026-8819", "original_end_to_end_id": "E2E-SEPA-2026-8819-A", "originating_bank_id": "bank_alpha", "destination_bank_id": "bank_beta", "debtor_iban": "DE89370400440532013000", "creditor_iban": "FR7630006000011234567890189", "amount": 49500.0, "currency": "EUR", "reason_code": "FRAD", "reason_narrative": "Authorized Push Payment fraud detected via impersonation syndicate." } ``` *Response (HTTP 201 Created):* ```json { "recall_id": "REC-2026-991204", "status": "INITIATED", "reason_code": "FRAD", "destination_account_frozen": true, "sla_deadline_iso": "2026-10-02T12:00:00Z", "days_remaining": 10, "recovery_transaction_id": "REC-HOLD-8819" } ``` **2. Resolve Recall Investigation with Dual Control (`POST /api/v1/recalls/{recall_id}/resolve`):** ```json { "resolution_code": "ACCEPTED", "supervisor_id": "SIG_SUPERVISOR_FINCRIME_44", "returned_amount": 49500.0, "resolution_notes": "Funds successfully quarantined on beneficiary mule account and queued for repatriation." } ``` ### 18.14 Real-Time Multi-List Sanctions & PEP Screening API (`/api/v1/screening/*`) Executes sub-10ms fuzzy matching across UN, EU CFSP, OFAC SDN, and PEP registries: **1. Screen Entity / Transaction Subject (`POST /api/v1/screening/screen`):** ```json { "entity_name": "Vladimir Petrovich Ivanov", "date_of_birth": "1974-05-12", "nationality": "RU", "threshold": 0.80 } ``` *Response (HTTP 200 OK):* ```json { "query_name": "Vladimir Petrovich Ivanov", "decision": "MATCH", "highest_score": 0.932, "matches": [ { "list_source": "EU_CFSP", "target_name": "Vladimir Petrovitch Ivanov", "composite_score": 0.932, "jw_score": 0.941, "lev_score": 0.918, "dob_match": true, "nationality_match": true, "sanction_program": "EU_UKRAINE_RESTRICTIONS_2026" } ], "whitelist_bypassed": false, "latency_ms": 3.4 } ``` ### 18.15 European FIU & UNODC goAML 4.0 / EU AMLA Regulatory Exporter API (`/api/v1/regulatory/*`) Compiles confirmed AML cases into standardized electronic filing packages: **1. Export UNODC goAML 4.0 XML (`POST /api/v1/regulatory/export/goaml-xml`):** ```json { "case_id": "CASE-2026-9941", "report_code": "STR", "fiu_destination": "FIU_GERMANY_ZFIU", "supervisor_id": "SIG_SUPERVISOR_AML_01" } ``` *Response (HTTP 200 OK):* ```json { "status": "GENERATED", "submission_id": "GOAML-STR-2026-9941-F12A", "schema_version": "goAML 4.0 XML", "xml_payload": "\n\n BANK_ALPHA_DE\n Cross-Bank Mule Structuring\n", "envelope_digest": "4a7b9c...e2f1", "created_at": "2026-09-22T21:40:00Z" } ``` ### 18.16 Enterprise AML OpenAPI Drop-in Adapter & Webhook Gateway (`/api/v2/*`, `/api/v1/*`) Provides backward-compatible drop-in endpoints matching industry-standard AML and transaction monitoring OpenAPI schemas, enabling member institutions to integrate existing core banking systems without bespoke integration middleware: **1. Ingest Corporate Legal Entity with Ultimate Beneficial Owners (`POST /api/v2/persons`):** ```json { "type": "LEGAL", "company_name": "Acrobat Capital Holdings B.V.", "registration_number": "NL-88392102", "country": "NL", "ubos": [ { "name": "David Alexander Meyer", "ownership_percentage": 68.5, "is_pep": false } ] } ``` *Response (HTTP 201 Created):* ```json { "person_id": "PER-LEGAL-7A2B9C", "status": "ACTIVE", "risk_tier": "MEDIUM", "ubo_count": 1, "created_at": "2026-09-22T21:45:00Z" } ``` **2. Execute Real-Time AML Monitoring Check (`POST /api/v1/transactions/{transaction_id}/monitoring-checks`):** ```json { "mode": "ONLINE", "direction": "OUTBOUND" } ``` *Response (HTTP 200 OK):* ```json { "transaction_id": "TX-AML-90218", "action": "SUSPEND", "risk_score": 884.0, "alerts": [ { "scenario_code": "SCN_EUR_STRUCTURING_SUB_10K", "severity": "CRITICAL", "description": "High-velocity structuring sequence below EUR 10,000 reporting threshold." } ], "latency_ms": 4.2 } ``` **3. Register HMAC-SHA256 Signed Webhook Ingestion Gateway (`POST /api/v1/webhook-subscriptions`):** ```json { "callback_url": "https://bank-alpha.internal.net/aml/events", "event_types": ["ALERT_CREATED", "SCREENING_ALERT_CREATED"] } ``` *Response (HTTP 201 Created):* ```json { "subscription_id": "SUB-AML-449102", "target_url": "https://bank-alpha.internal.net/aml/events", "status": "ACTIVE", "signing_secret": "whsec_7f9a...3b2c", "subscribed_events": ["ALERT_CREATED", "SCREENING_ALERT_CREATED"] } ``` ### 18.17 Cross-Border Corporate UBO & Heterogeneous Graph Intelligence API (`/api/v1/ubo/*`) Provides consortium-wide graph intelligence for multi-tier Ultimate Beneficial Owner (UBO) calculation, circular ownership loop identification, nominee director syndicate detection, and offshore shell company clustering: **1. Calculate Multi-Tier Compounded Beneficial Ownership (`GET /api/v1/ubo/entities/{entity_id}/beneficial-owners?threshold=25.0&max_depth=8`):** *Response (HTTP 200 OK):* ```json { "entity_id": "ORG-LUX-HOLDING", "statutory_threshold": 25.0, "beneficial_owners": [ { "node_id": "PER-UBO-ALICE", "name": "Alice Vance", "node_type": "NATURAL_PERSON", "jurisdiction": "DE", "direct_percentage": 15.0, "indirect_percentage": 12.5, "effective_percentage": 27.5, "reaches_statutory_threshold": true, "is_pep": false, "is_sanctioned": false, "shortest_hop_distance": 1, "control_paths": [ ["PER-UBO-ALICE", "ORG-LUX-HOLDING"], ["PER-UBO-ALICE", "ORG-NL-BV", "ORG-LUX-HOLDING"] ] } ], "total_beneficial_owners_identified": 1, "depth_analyzed": 2, "calculated_at": "2026-09-22T21:50:00Z" } ``` **2. Audit Entity for Structural Corporate Anomalies (`GET /api/v1/ubo/entities/{entity_id}/anomalies`):** *Response (HTTP 200 OK):* ```json { "target_entity_id": "ORG-SHELL-CYPRUS", "anomalies_detected": [ { "anomaly_type": "CIRCULAR_OWNERSHIP", "severity": "CRITICAL", "description": "Directed circular ownership loop detected across 3 entities.", "involved_entities": ["ORG-SHELL-CYPRUS", "ORG-BVI-HOLDINGS", "ORG-MALTA-CORP"], "confidence_score": 1.0, "detected_at": "2026-09-22T21:50:05Z" } ], "has_circular_ownership": true, "has_nominee_directors": false, "has_high_risk_offshore": true, "has_pep_or_sanctions_exposure": false, "composite_structural_risk_score": 85.0 } ``` **3. Export Directed Ego-Subgraph for Interactive Visualizer (`GET /api/v1/ubo/entities/{entity_id}/subgraph?max_hops=3`):** *Response (HTTP 200 OK):* ```json { "root_id": "ORG-LUX-HOLDING", "nodes": [ {"node_id": "ORG-LUX-HOLDING", "name": "Luxembourg Holdings S.A.", "node_type": "LEGAL_ENTITY", "jurisdiction": "LU"}, {"node_id": "PER-UBO-ALICE", "name": "Alice Vance", "node_type": "NATURAL_PERSON", "jurisdiction": "DE"} ], "edges": [ {"source_id": "PER-UBO-ALICE", "target_id": "ORG-LUX-HOLDING", "relation_type": "DIRECT_OWNERSHIP", "percentage": 15.0} ], "total_nodes": 2, "total_edges": 1 } ``` ### 18.18 European AML Monitoring Scenario Library & Hybrid Deterministic Rule Engine API (`/api/v1/scenarios/european-aml/*`) Provides 16 pre-configured statutory European AML monitoring rules and a hybrid scoring synthesizer that blends deterministic compliance rule penalties with Federated GNN risk embeddings into an explainable composite decision: **1. Real-Time Hybrid AML Risk Evaluation (`POST /api/v1/scenarios/european-aml/evaluate`):** ```json { "transaction": { "transaction_id": "TX-EUR-90218", "amount": 9500.0, "currency": "EUR", "originator_id": "CUST-ALICE-100", "beneficiary_id": "CUST-BOB-200", "origin_country": "DE", "destination_country": "FR", "payment_rail": "SEPA_INSTANT", "recent_distinct_counterparties_24h": 1, "funds_retention_ratio": 1.0 }, "ml_risk_score": 0.35, "strict_regulatory_override": true } ``` *Response (HTTP 200 OK):* ```json { "transaction_id": "TX-EUR-90218", "action": "MANUAL_REVIEW", "composite_risk_score": 533.5, "rule_penalty_score": 320.0, "ml_risk_score": 0.35, "ml_penalty_equivalent": 350.0, "regulatory_override_applied": false, "triggered_scenarios": [ { "scenario_code": "SCN_EUR_STRUCTURING_SUB_10K", "scenario_name": "Sub-€10,000 Threshold Structuring (Smurfing)", "category": "STRUCTURING", "severity": "HIGH", "penalty_score": 320.0, "regulatory_citation": "EU AMLD6 Art. 33 & FATF Recommendation 10", "trigger_rationale": "Transfer of €9,500.00 positioned just below the €10,000 statutory reporting threshold." } ], "total_scenarios_evaluated": 16, "total_scenarios_triggered": 1, "explainability_narrative": "Action 'MANUAL_REVIEW' decided with composite risk 533.5/1000. Triggered 1 European AML scenario(s): [SCN_EUR_STRUCTURING_SUB_10K].", "evaluated_at": "2026-09-23T00:05:00Z" } ``` **2. Query European AML Scenario Library Catalog (`GET /api/v1/scenarios/european-aml/library`):** *Response (HTTP 200 OK):* ```json { "total_scenarios": 16, "scenarios": [ { "scenario_code": "SCN_EUR_STRUCTURING_SUB_10K", "name": "Sub-€10,000 Threshold Structuring (Smurfing)", "category": "STRUCTURING", "severity": "HIGH", "base_penalty": 320.0, "regulatory_basis": "EU AMLD6 Art. 33 & FATF Recommendation 10", "description": "Transaction structured immediately below the €10,000 European statutory reporting threshold." } ] } ``` ### 18.19 Asset Recovery & Collaborative FININT Operational Hub API (`/api/v1/operations/asset-recovery/*`) Provides real-time aggregated financial containment and MTTR operational telemetry across all ISO 20022 `camt.056` payment recalls and inter-bank FININT provisional holds: **1. Aggregated Operational Summary (`GET /api/v1/operations/asset-recovery/summary`):** *Response (HTTP 200 OK):* ```json { "total_recovered_eur": 2845000.0, "total_frozen_eur": 1920000.0, "total_events_count": 11, "successful_recalls_count": 5, "provisional_holds_count": 4, "partial_recoveries_count": 2, "mttr_minutes_p50": 18.5, "mttr_minutes_p90": 42.0, "mttr_minutes_p99": 75.0, "legacy_baseline_mttr_minutes": 2880.0, "mttr_reduction_percent": 99.36, "cross_bank_contagion_containment_rate": 90.91, "mule_chains_disrupted": 7, "last_audit_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "generated_at": "2026-09-23T12:00:00Z" } ``` **2. Per-Typology Containment Breakdown (`GET /api/v1/operations/asset-recovery/breakdown-by-typology`):** *Response (HTTP 200 OK):* ```json [ { "typology": "CRYPTO_CASHOUT", "total_eur": 1250000.0, "events_count": 3, "avg_mttr_minutes": 14.2, "containment_rate": 100.0, "risk_level": "CRITICAL" }, { "typology": "APP_FRAUD_MULE_CHAIN", "total_eur": 850000.0, "events_count": 2, "avg_mttr_minutes": 22.5, "containment_rate": 100.0, "risk_level": "HIGH" } ] ``` ### 18.20 Federated Learning Coordinator & Bank Node Telemetry API (`/api/v1/coordinator/*`) Provides real-time bank edge-node registration, institutional hardware capability telemetry (PyTorch 2.4.0, CUDA/CPU, VRAM/RAM), asynchronous staleness aggregation, and dynamic hyperparameter negotiation across consortium institutions: > **Consortium Simulation Testbed Notice:** > All banking institutions, node identifiers, and telemetry payloads represented in this platform (`Bank Alpha`, `Bank Beta`, `Bank Gamma`, `Meridian National`, `Nexus Digital`) are **purely synthetic simulation testbed entities**. CF-Intelligence does not connect to live commercial banking networks, core banking ledgers, SWIFT messaging infrastructure, or real financial institutions. **1. Query Registered Consortium Clients & Telemetry (`GET /api/v1/coordinator/clients`):** *Response (HTTP 200 OK):* ```json [ { "bank_id": "bank_alpha", "bank_name": "Bank Alpha (Synthetic Retail Node)", "pytorch_version": "2.4.0+cu124", "python_version": "3.12.3", "hardware_type": "cuda", "ram_gb": 128.0, "device_count": 4, "status": "ONLINE", "last_heartbeat": 1758921600.0, "registered_at": 1758921500.0 }, { "bank_id": "bank_beta", "bank_name": "Bank Beta (Synthetic Commercial Node)", "pytorch_version": "2.4.0+cu124", "python_version": "3.12.3", "hardware_type": "cuda", "ram_gb": 64.0, "device_count": 2, "status": "ONLINE", "last_heartbeat": 1758921600.0, "registered_at": 1758921500.0 } ] ``` **2. Bank Node Handshake & Capability Exchange (`POST /api/v1/coordinator/handshake`):** ```json { "bank_id": "bank_gamma", "bank_name": "Bank Gamma (Synthetic Regional Node)", "pytorch_version": "2.4.0+cu121", "python_version": "3.12.2", "hardware_type": "cuda", "ram_gb": 64.0, "device_count": 2 } ``` *Response (HTTP 200 OK):* ```json { "registered": true, "bank_id": "bank_gamma", "status": "COMPATIBLE", "registered_at": 1758921600.0, "message": "Handshake successful with PyTorch 2.4.0+cu121." } ``` **3. Dynamic Hardware-Aware Hyperparameter Negotiation (`POST /api/v1/coordinator/negotiate`):** ```json { "bank_id": "bank_alpha", "base_batch_size": 64, "base_epochs": 5 } ``` *Response (HTTP 200 OK):* ```json { "bank_id": "bank_alpha", "batch_size": 64, "local_epochs": 5, "use_cuda": true, "gradient_accumulation_steps": 1, "status": "COMPATIBLE" } ``` ---