POST /wallets/screen

Resumo

Rota do dashboard (JWT + papel Analista ou superior + MFA fresco), não da superfície de API key. Recebe o SHA-256 hex do endereço (address_hash; o endereço bruto nunca trafega, política LGPD) + blockchain, busca na base de carteiras do tenant e retorna risk score + metadata + exposições. Carteira desconhecida recebe score default e entra no radar contínuo (watchlist).

Para decisão KYT máquina-a-máquina use POST /vasp/screenings com X-API-Key.

Request

Headers

Header	Required	Valor
Authorization	✅	Bearer <JWT do login>
Content-Type	✅	application/json

Body

{
  "address_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "blockchain": "TRON"
}

Campo	Tipo	Required	Descrição
address_hash	string	✅	SHA-256 hex do endereço da carteira
blockchain	string	✅	Código da rede usado no cadastro da carteira (cobertura real: 24 redes)

Response 200 (carteira conhecida)

{
  "success": true,
  "wallet_id": "9c2a1b3e-...",
  "risk_score": 95,
  "risk_tier": "CRITICAL",
  "metadata": {
    "sanctioned": true,
    "sanction_program": "SDGT",
    "sanction_date": "2025-04-02",
    "entity": "Houthi Group (Ansarallah)",
    "context": "Designated under EO 13224 for financing terrorism"
  },
  "labels": ["sanction", "terrorism"],
  "mixer_exposure": 0.0,
  "sanctions_exposure": 1.0,
  "scam_exposure": 0.0,
  "is_blocklisted": true,
  "blocklist_reason": "OFAC SDGT Houthi designation",
  "vasp_name": null,
  "vasp_country": null
}

Response 200 (carteira desconhecida, primeira vez)

A carteira ainda não existe na base do tenant: o handler responde apenas o score default e registra a carteira no radar contínuo.

{
  "success": true,
  "risk_score": 0,
  "risk_tier": "GREEN"
}

Response 400 (payload inválido)

{
  "success": false,
  "error": "Address hash and blockchain are required."
}

Response 401 (sem JWT válido)

A rota é JWT: chamadas com X-API-Key retornam 401.

Cuidado

Quando receber 5xx: NÃO use mock como fallback. O backend está degradado e um mock pode mascarar uma sanção real. Aborte ou re-tente.

Risk score breakdown

Score	Tier	Ação recomendada
0-29	GREEN	Aprovar
30-59	AMBER	Review opcional + monitorar
60-79	RED	Review obrigatório
80+	CRITICAL	Bloquear + SAR-COAF em 24h

Códigos de exposure

• mixer_exposure: 0-1, proporção de fundos vindos de mixers (Tornado Cash etc.)
• sanctions_exposure: 0-1, proporção de fundos vindos de carteiras sancionadas
• scam_exposure: 0-1, proporção de fundos vindos de scams reportados