Quando usar
A triagem de carteiras não grava nada na tabela de transações. Se você precisa que a triagem fique vinculada a uma transação monitorada (com regras, alertas e webhooks), envie uma transação.
Pré-requisitos
O monitoramento de transações precisa estar configurado para a aplicação com um provedor gerenciado ou uma chave de provedor existente. Configure-o em Transações > Configurações > Provider Preferences no Business Console. Se nenhum provedor estiver configurado, o endpoint retorna409 Conflict.
Requisição
POST https://verification.didit.me/v3/wallet-screening/
Autentique-se com o cabeçalho x-api-key.
Cobertura de redes
A triagem gerenciada oferece suporte a Base (BASE), Optimism (OP) e Arbitrum One (ARB), tanto para triagem de carteiras quanto de hash de transação.
Provedores conectados podem ter cobertura diferente; a rede também precisa ser suportada pelo provedor e pela conta que você selecionou.
Celo (CELO), Mode (MODE) e Plume (PLUME) são analisadas por meio de uma conta TRM Labs conectada (Marketplace, com sua própria chave); a triagem gerenciada não cobre essas redes e retorna 400.
Não envie ETH para outra rede EVM: o mesmo endereço pode ter atividade e risco diferentes em cada rede.
Na triagem gerenciada, USDT e USDC são aliases legados para Ethereum, e não uma busca em todas as redes em que esses tokens existem.
Use o identificador da rede (ETH, TRX, SOL, MATIC, BNB, BASE, OP, ARB, AVAX, ADA, XLM, HBAR ou, com TRM Labs, CELO, MODE ou PLUME) correspondente à rede usada pela carteira.
Para tokens em transações registradas, mantenha o token em transaction_details.currency e especifique a rede separadamente em transaction_details.crypto_params.crypto_chain.
Veja seleção de ativo e rede.
Resposta
A resposta é o resultado de triagem padronizado, com o mesmo formato do resultado de provedorWALLET_SCREENING retornado pela triagem de transações.
Como
severity é definido. severity é a faixa da risk_score normalizada: 0-9 → UNKNOWN, 10-39 → LOW, 40-69 → MEDIUM, 70-89 → HIGH, 90-100 → CRITICAL. UNKNOWN é a faixa mais baixa, e não um estado separado de “sem dados”: risk_score: 0 (o caso comum de endereço limpo) significa que o provedor não retornou nenhuma avaliação adversa, enquanto uma pontuação diferente de zero na faixa 1-9 é um sinal real, mas abaixo de LOW. Por isso, leia a própria risk_score, e não apenas a faixa. Em qualquer caso, não apresente UNKNOWN como um “liberado” afirmativo nem como uma aprovação.direction não altera o modelo de risco. O campo opcional direction é repassado ao provedor apenas como contexto. Ele não afeta risk_score, severity nem quais listas de detalhamento são retornadas: source_of_funds e destination_of_funds são sempre retornados, independentemente desse campo. Portanto, alterar ou omitir direction não exige refazer a triagem de um endereço já analisado.Fatores de risco
risk_factors é a resposta ranqueada para a pergunta “por que este endereço recebeu esta pontuação”. Os provedores classificam um endereço com o próprio modelo e retornam apenas um veredito (a Merkle Science retorna um inteiro 0-5), então não é possível agir com base apenas em risk_score. Cada entrada indica um fator determinante, com os de alto risco primeiro e, em seguida, ordenados pelo valor que passou por eles.
Uma pontuação alta sem nenhum fator
is_high_risk é um resultado real e significativo. Isso significa que o provedor classificou o endereço com o próprio modelo de exposição sem reportar uma correspondência com sanções, PEP ou entidade atribuída; os fatores que estão listados são os fluxos de fundos por trás da classificação. summary informa isso explicitamente, então trate esses endereços como “revisar os fluxos”, e não como uma ocorrência confirmada. risk_factors é limitado aos cinco fatores mais fortes; source_of_funds e destination_of_funds sempre trazem o detalhamento completo.risk_factors é um campo de nível superior, não aninhado. Resultados analisados antes de ele existir omitem a chave por completo: trate-a como uma lista vazia, em vez de supor uma explicação vazia.Detalhamento da exposição
Cada entrada emsource_of_funds / destination_of_funds descreve uma entidade com a qual o endereço trocou fundos:
Conexões com contrapartes
counterparty_connections lista as entidades às quais o provedor atribui o endereço analisado. Para Merkle Science, elas vêm das tags de proprietário e de usuário do próprio endereço, por isso a mesma entidade pode aparecer duas vezes, e não trazem fluxos de fundos: received_usd, sent_usd, received_hops e sent_hops são null, e percentage é 0.0. Leia os fluxos de fundos em source_of_funds e destination_of_funds.
Exemplo
Uma resposta real para um endereço na lista de sanções da OFAC, analisado com Merkle Science. Apenasraw_response foi encurtado e report_signature foi substituído:
sanctions_hit: true pode indicar que a própria carteira é sancionada ou apenas que seus fundos têm exposição a sanções, portanto isso, por si só, não significa que o titular da carteira analisada seja sancionado.
Quando a mesma análise é executada sobre uma transação registrada, as regras também podem ler custom_values.wallet_sanctioned, que é true somente quando o provedor atribui a própria carteira a uma entidade sancionada, e custom_values.aml_sanctions_exposure_pct.
Consulte Campos de análise para regras.
Leia risk_factors, source_of_funds e destination_of_funds para distinguir atribuição de exposição.
Consulte Triagem de cripto e de carteiras para um passo a passo.
Relatório em PDF
Para obter um PDF com a marca Didit de um resultado de triagem, reenvie o corpo exato da resposta, incluindoreport_signature, para POST /v3/wallet-screening/pdf/. A operação é stateless: nenhuma chamada ao provedor, nenhum faturamento adicional, nada é persistido. Se você editar qualquer campo assinado (risk_score, severity, sanctions_hit, …) antes de reenviar, a requisição falha com 400.
Faturamento
Cada uso de monitoramento AML é cobrado por triagem bem-sucedida, com a mesma tarifa da triagem de cripto vinculada a transações. Consulte os preços para ver as tarifas para chaves gerenciadas e conectadas. Aplicações de sandbox não são cobradas. Erros de validação (400) e erros de provedor não configurado (409) nunca são cobrados.
Erros
Próximos passos
Referência da API
Esquema completo de requisição e resposta do endpoint Screen Wallet.
PDF da triagem de carteira
Gere um PDF com a marca Didit a partir de um resultado de triagem.
Triagem de cripto e carteiras
Triagem automática durante a criação de transações e o modelo de resultado.