Pular para o conteúdo principal
Às vezes você precisa verificar o risco AML de uma carteira cripto antes de existir qualquer transação a registrar, por exemplo, quando um cliente adiciona um endereço de saque ou quando sua equipe de conformidade quer avaliar um endereço pontualmente. O endpoint de triagem de carteiras sob demanda analisa um único endereço e retorna o resultado de risco completo sem criar uma transação. Esta é a versão independente da triagem cripto automática executada durante o envio de transações. Os dois usam os mesmos provedores de análise de blockchain e o mesmo formato de resultado.

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 retorna 409 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.
LIGHTNING está disponível somente quando a aplicação tem um provedor BYOK da Elliptic ou da Chainalysis conectado no Marketplace do console. Não está disponível com a Merkle Science gerenciada nem com Crystal ou TRM Labs. Requisições sem um provedor conectado compatível retornam 400 e não são analisadas nem cobradas.

Resposta

A resposta é o resultado de triagem padronizado, com o mesmo formato do resultado de provedor WALLET_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 em source_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.
Não tome decisões de roteamento com base em counterparty_connections[].risk_level ou counterparty_connections[].is_direct: para Merkle Science, o primeiro repete a própria classificação do endereço (leia risk_score) e o segundo é sempre true. Use sanctions_hit, dominant_risk_category e risk_factors[].is_high_risk para o veredito, e exposure_type em source_of_funds / destination_of_funds para saber se a exposição é direta.

Exemplo

Uma resposta real para um endereço na lista de sanções da OFAC, analisado com Merkle Science. Apenas raw_response foi encurtado e report_signature foi substituído:
Os exemplos ilustram o formato da resposta, não um veredito garantido para um endereço real. As pontuações de risco e a exposição a sanções dependem da rede selecionada, da inteligência atual e da política de risco configurada. Uma atribuição a uma exchange não implica pontuação de risco zero: uma carteira de exchange pode ter exposição a sanções por meio de seus fluxos de fundos. 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, incluindo report_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.
Consulte PDF da triagem de carteira para ver o esquema completo de requisição e resposta e os formatos de erro.

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.
Última modificação em 1 de novembro de 2026