> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# API de triagem de cripto e carteiras

> A Didit faz triagem de carteiras e hashes de transação com pontuação de risco, exposição e grafos de rede. Triagem de carteira a partir de $0.15.

Em transações de criptomoedas, a Didit pode fazer a triagem de endereços de carteira e hashes de transação usando provedores de análise de blockchain como Merkle Science, Crystal, Chainalysis, Elliptic e TRM Labs durante a criação da transação. A triagem é executada no servidor: nenhuma chamada de API adicional é necessária do seu lado.

> [!TIP]
>
> Precisa fazer a triagem de um endereço **sem** uma transação? Use o endpoint de [triagem de carteiras sob demanda](https://docs.didit.me/pt-br/transaction-monitoring/wallet-screening.md) (`POST /v3/wallet-screening/`) para obter o mesmo resultado de risco para uma carteira com uma só chamada de API.

## Como a triagem é acionada

A triagem de cripto é executada automaticamente quando as duas condições são atendidas:

1. A transação tem `currency_kind: "crypto"` nos detalhes da transação
2. O monitoramento de transações está ativado nas [configurações da aplicação](https://docs.didit.me/pt-br/transaction-monitoring/settings.md)

Você pode substituir esse padrão por transação com `include_crypto_screening` no payload de criação da transação:

| Valor | Comportamento |
| - | - |
| `true` | Executa a triagem de cripto mesmo que o padrão no nível da aplicação esteja desativado |
| `false` | Ignora a triagem de cripto mesmo que o padrão no nível da aplicação esteja ativado |
| omitido ou `null` | Usa o padrão no nível da aplicação configurado no Console |

> [!TIP]
>
> O padrão no nível da aplicação fica em **Transactions** > **Settings** no Business Console. `include_crypto_screening` só substitui esse padrão para a transação específica que você está criando.

## Seleção de ativo e rede

O ativo e a rede são campos separados.
Defina `transaction_details.currency` como o símbolo do token, `transaction_details.currency_kind` como `crypto` e `transaction_details.crypto_params.crypto_chain` como a rede.
Por exemplo, este trecho registra um token personalizado na Base:

```json theme={null}
{
  "transaction_details": {
    "currency": "TOKEN",
    "currency_kind": "crypto",
    "crypto_params": {"crypto_chain": "BASE"}
  }
}
```

A triagem gerenciada aceita `BTC`, `ETH`, `LTC`, `XRP`, `BCH`, `DOGE`, `TRX`, `SOL`, `MATIC`, `BNB`, `BASE`, `OP`, `ARB`, `AVAX`, `ADA`, `XLM` e `HBAR`.
`BASE` significa Base, `OP` significa Optimism, `ARB` significa Arbitrum One, `AVAX` significa Avalanche C-Chain, `ADA` significa Cardano, `XLM` significa Stellar e `HBAR` significa Hedera.
Nomes comuns de redes também são aceitos, por exemplo `POLYGON` ou `POL` para `MATIC`, `BSC` para `BNB` e `TRON` para `TRX`.
Celo, Mode e Plume não são cobertas pela integração gerenciada; elas são analisadas por meio de uma conta TRM Labs conectada (`CELO`, `MODE`, `PLUME`).
Os provedores conectados têm a própria cobertura; a Lightning tem requisitos adicionais, descritos abaixo.

Sempre especifique `crypto_chain` para um token, inclusive USDT e USDC.
Sem ele, a moeda é usada como rede, e USDT e USDC obtêm a rede a partir do hash da transação ou, sem hash, a partir do endereço da carteira.
Um hash da Tron ou da Solana seleciona Tron ou Solana.
Um hash `0x` tem a mesma aparência em todas as redes EVM, então, para USDT, USDC e ETH, a Didit o procura em Ethereum, BNB Chain, Polygon, Base, Arbitrum e Optimism e analisa a transação na rede em que ele for encontrado.
O ETH está incluído porque é nativo em Ethereum, Base, Arbitrum e Optimism e também é transferido na BNB Chain como um token BEP-20 bridged.
Se nenhuma rede tiver o hash, ou se não for possível verificar as redes naquele momento, a transação não é analisada e a triagem não é cobrada.
Nesse caso, `custom_values.aml_screening_status` fica como `FAILED`, `custom_values.aml_screening_error` informa o motivo e uma transação aprovada passa para revisão.

Uma transação em USDT ou USDC sem hash analisa uma carteira, e o endereço da carteira seleciona a rede.
Um endereço da Tron é analisado na Tron e um endereço da Solana, na Solana.
Um endereço `0x` é analisado na primeira rede, entre Ethereum, BNB Chain, Polygon, Base, Arbitrum e Optimism, em que ele tenha enviado uma transação ou detenha o token.
Um endereço `0x` sem atividade em nenhuma delas, ou cujas redes não possam ser verificadas naquele momento, é analisado na Ethereum.

Enviar `crypto_chain` evita a busca.
Nunca use `ETH` no lugar da rede real.

Registrar um símbolo de token personalizado não garante que as transferências dele sejam indexadas para a triagem por hash de transação.
A cobertura do token deve ser verificada usando o contrato do token e a rede.
Uma transação criada não é prova de triagem bem-sucedida: verifique o status da triagem e o resultado do provedor antes de considerá-la analisada.

## Entrada vs. saída

`transaction_details.direction` é obrigatório porque informa à Didit qual lado da transferência deve ser analisado.

| Direção | Antes da transferência on-chain | Depois da transferência on-chain |
| - | - | - |
| **Entrada** (depósitos) | Analisa a carteira remetente da contraparte, se você a informar em `counterparty.payment_method.account_id` | Analisa o hash da transação associado ao endereço de depósito do seu serviço ou cliente em `subject.payment_method.account_id` |
| **Saída** (saques) | Analisa a carteira de destino em `counterparty.payment_method.account_id` antes de você enviar os fundos | Analisa o hash da transação associado à mesma carteira de destino em `counterparty.payment_method.account_id` |

Para a triagem antes da transferência, omita `transaction_details.payment_reference_id`; a Didit executa a triagem do endereço da carteira relevante. Para a triagem depois da transferência, inclua o hash da transação na blockchain em `transaction_details.payment_reference_id`; a Didit executa a triagem da transação e armazena dados de resumo da transação quando o enriquecimento on-chain está disponível.

### Lightning Network

Defina `transaction_details.crypto_params.crypto_chain` como `LIGHTNING` para a triagem na Lightning Network.
A triagem na Lightning exige um provedor BYOK da Elliptic ou da Chainalysis conectado no **Marketplace** do console.
Merkle Science, Crystal e TRM Labs gerenciados não aceitam `LIGHTNING`; a Didit recusa essas requisições com `400` antes da triagem ou do faturamento.

Com a Elliptic, a Didit analisa o identificador Lightning informado por meio da análise de carteiras BTC Lightning da Elliptic.
Com a Chainalysis, a Didit envia uma transferência Lightning ao KYT quando `transaction_details.payment_reference_id` está presente.

## Campos obrigatórios

Em todas as requisições de análise de cripto, envie:

* `transaction_details.direction` — `INBOUND` ou `OUTBOUND`
* `transaction_details.currency_kind` — `crypto`
* `transaction_details.currency` — o símbolo do ativo, por exemplo `BTC`, `ETH`, `USDC` ou seu token personalizado
* Um endereço de carteira autocustodiada no participante selecionado pelas regras de direção acima

Para a análise por hash de transação depois que a transferência estiver on-chain, envie também:

* `transaction_details.payment_reference_id` — o hash da transação na blockchain

Se a análise de cripto estiver ativada e faltar o endereço de carteira exigido para a direção, a API de criação de transação recusa a requisição.

## Exemplo: análise de saída antes da transferência

Antes de enviar fundos, crie uma transação de criptomoeda de saída sem hash de transação. A Didit analisa a carteira de destino.

```json theme={null}
{
  "transaction_id": "withdrawal-001",
  "transaction_category": "finance",
  "include_crypto_screening": true,
  "transaction_details": {
    "direction": "OUTBOUND",
    "amount": "0.25",
    "currency": "ETH",
    "currency_kind": "crypto",
    "action_type": "withdrawal"
  },
  "subject": {
    "entity_type": "individual",
    "vendor_data": "user-123",
    "full_name": "John Doe"
  },
  "counterparty": {
    "entity_type": "unhosted_wallet",
    "full_name": "John Doe",
    "payment_method": {
      "method_type": "crypto_wallet",
      "account_id": "0xRecipientWallet..."
    }
  }
}
```

## Exemplo: análise de transação de entrada após a transferência

Depois de receber fundos, inclua o hash da transação. A Didit analisa o hash da transação considerando seu endereço de depósito e complementa a resposta com informações resumidas da transação, quando disponíveis.

```json theme={null}
{
  "transaction_id": "deposit-001",
  "transaction_category": "finance",
  "include_crypto_screening": true,
  "transaction_details": {
    "direction": "INBOUND",
    "amount": "0.25",
    "currency": "ETH",
    "currency_kind": "crypto",
    "action_type": "deposit",
    "payment_reference_id": "0xTransactionHash..."
  },
  "subject": {
    "entity_type": "individual",
    "vendor_data": "user-123",
    "full_name": "John Doe",
    "payment_method": {
      "method_type": "crypto_wallet",
      "account_id": "0xYourServiceDepositAddress..."
    }
  },
  "counterparty": {
    "entity_type": "unhosted_wallet",
    "full_name": "John Doe"
  }
}
```

## Provedores compatíveis

| Provedor | Status | Preço do serviço gerenciado | Preço com chave conectada |
| - | - | - | - |
| **Merkle Science** | Disponível | \$0.15/análise | \$0.02/análise |
| **Crystal** | Conecte uma chave do provedor pelo Marketplace | Não disponível | \$0.02/análise |
| **Chainalysis** | Conecte uma chave do provedor pelo Marketplace | Não disponível | \$0.02/análise |
| **Elliptic** | Conecte uma chave do provedor pelo Marketplace | Não disponível | \$0.02/análise |
| **TRM Labs** | Conecte uma chave do provedor pelo Marketplace | Não disponível | \$0.02/análise |

Configure seu provedor preferido em **Transactions** > **Settings** > **Provider Preferences** no [Business Console](https://business.didit.me), ou conecte sua própria chave de API do provedor no **Marketplace** do console (categoria Crypto monitoring).

`LIGHTNING` é compatível apenas com as configurações de Chainalysis e Elliptic com chave conectada.

> [!TIP]
>
> Com o **preço com chave conectada**, você conecta uma chave de API de provedor que já possui e paga a taxa de infraestrutura indicada por análise. Use essa opção quando já tiver um contrato comercial com um provedor de análise de blockchain.

## Resultados da triagem

Cada triagem produz um resultado padronizado, independentemente do provedor utilizado.

### Status da triagem

`custom_values.aml_screening_status` indica se uma transação foi analisada.

| Valor | Significado |
| - | - |
| `COMPLETED` | A triagem foi concluída. O resultado está em `provider_results` e nos demais campos de triagem de `custom_values`. |
| `PENDING` | A triagem ainda não foi concluída: o provedor ainda está fazendo a análise, ou a Didit analisa o hash da transação novamente mais tarde (veja abaixo). |
| `ERROR` | O provedor respondeu, mas informou que a própria análise falhou. |
| `FAILED` | A transação não foi analisada. `custom_values.aml_screening_error` informa o motivo. A triagem gerenciada pela Didit não cobra nada por isso; uma requisição respondida pelo seu provedor conectado conta como uma requisição ao provedor. |

Uma transação que seria aprovada passa para `IN_REVIEW` enquanto a triagem estiver em qualquer status diferente de `COMPLETED`.

### Hashes de transação ainda não indexados

Um provedor de análise de blockchain pode levar alguns minutos para indexar uma transferência recém-minerada e, até lá, não consegue analisá-la.
Quando o provedor responde que ainda não indexou um hash de transação, e a própria rede confirma que a transação existe, a Didit a analisa novamente em segundo plano em vez de marcá-la como falha:

* A resposta de criação já mostra `custom_values.aml_screening_status` como `PENDING`, com o motivo em `custom_values.aml_screening_error`.
  Uma transação que, de outra forma, seria aprovada fica retida em `IN_REVIEW` com `decision_reason_code` `aml_screening_pending`.
* A Didit analisa o hash da transação novamente cerca de 2, 12 e 42 minutos após a criação da transação.
* Quando uma nova tentativa consegue analisá-la, o resultado é armazenado como em qualquer outra triagem e a triagem é cobrada uma única vez.
  Suas regras são executadas novamente sobre os dados da triagem, a retenção é liberada e você recebe um webhook `transaction.status.updated` com o status que a transação tem após as regras, tenha ele mudado ou não.
  Uma transação que foi recusada ou resolvida por um revisor nesse meio-tempo mantém o seu status.
* Se o provedor ainda não tiver indexado o hash da transação após a última tentativa, a triagem termina como `FAILED`, como teria terminado na criação: a transação permanece em `IN_REVIEW` com `decision_reason_code` `aml_screening_failed`, e a cobrança é a mesma de uma falha na criação: nada na triagem gerenciada pela Didit, uma requisição ao provedor quando a última tentativa chegou ao seu provedor conectado. As tentativas anteriores que exigiram nova tentativa nunca são cobradas.
* Se o seu saldo não puder mais cobrir a triagem quando uma nova tentativa for executada, a triagem termina como `FAILED` e nada é cobrado.

As novas tentativas se aplicam a hashes de transação em Ethereum, BNB Chain, Polygon, Base, Arbitrum, Optimism e Tron.
Um hash que a rede não conhece, ou um hash em outra rede, não recebe novas tentativas: a triagem falha imediatamente.

### Pontuação de risco e severidade

Cada carteira ou transação analisada recebe:

* **Pontuação de risco** (0–100) — pontuações mais altas indicam maior exposição a entidades de risco
* **Nível de severidade** — derivado da pontuação: `LOW`, `MEDIUM`, `HIGH` ou `CRITICAL`

### Análise da origem dos recursos

Uma divisão percentual de onde os recursos se originaram, categorizada por tipo de entidade:

| Categoria | Nível de risco | Descrição |
| - | - | - |
| `SANCTIONED` | Crítico | Entidades em listas de sanções internacionais (OFAC, UE, ONU) |
| `TERRORIST_FINANCING` | Crítico | Endereços vinculados ao financiamento do terrorismo |
| `CHILD_EXPLOITATION` | Crítico | Endereços vinculados a material de exploração infantil |
| `RANSOMWARE` | Alto | Endereços de pagamento de ransomware |
| `STOLEN_FUNDS` | Alto | Endereços associados a roubos ou ataques hackers conhecidos |
| `DARKNET_MARKET` | Alto | Endereços de marketplaces da darknet |
| `MIXER` | Alto | Serviços de mixing ou tumbling usados para ocultar a origem dos recursos |
| `SCAM` | Alto | Endereços conhecidos de golpes ou fraudes |
| `HIGH_RISK_EXCHANGE` | Médio | Exchanges com controles de KYC/AML fracos |
| `HIGH_RISK_JURISDICTION` | Médio | Entidades em jurisdições de alto risco listadas pelo GAFI (FATF) |
| `GAMBLING_UNLICENSED` | Médio | Plataformas de apostas sem licença |
| `P2P_EXCHANGE` | Baixo | Serviços de troca peer-to-peer |
| `EXCHANGE` | Baixo | Exchanges de criptomoedas regulamentadas |
| `UNNAMED_SERVICE` | Baixo | Serviços não identificados |

Cada entidade na divisão inclui o percentual dos recursos, os valores recebidos e enviados e se a conexão é direta ou indireta.

### Tabela de exposição

Uma tabela de exposição que mostra as entidades de origem, de destino e contrapartes, incluindo:

* Nome e categoria da entidade
* Conexão direta ou indireta (número de saltos)
* Valores recebidos e enviados
* Nível de risco por entidade

### Grafo de rede

Uma representação visual em nós e arestas das relações de transação da carteira:

* **Nós** representam carteiras, exchanges, serviços e outras entidades
* **Arestas** representam transações entre nós, com valores e hashes de transação
* **Métricas** incluem estatísticas do grafo, como centralidade e profundidade

O grafo de rede está disponível no [Business Console](https://docs.didit.me/pt-br/transaction-monitoring/console.md) como uma visualização interativa.

## Integração com regras

Os resultados da análise alimentam diretamente o [mecanismo de regras](https://docs.didit.me/pt-br/transaction-monitoring/rules.md). A Didit inclui regras predefinidas que são acionadas automaticamente com base nos dados da análise:

| Regra predefinida | Ação |
| - | - |
| **Sanctions counterparty** | Recusa imediata: a própria carteira analisada é atribuída a uma entidade sancionada (`custom_values.wallet_sanctioned`) |
| **Exposição a sanções** | Adiciona pontuação + sinaliza para revisão: a carteira movimentou fundos para ou de entidades sancionadas sem ser ela mesma sancionada (`sanctions_hit` true, `wallet_sanctioned` diferente de true) |
| **Terrorist financing / child exploitation** | Recusa imediata |
| **Darknet market exposure** | Adiciona pontuação + sinaliza para revisão |
| **Mixer/obfuscation service exposure** | Adiciona pontuação + sinaliza para revisão |
| **High-risk source of funds (>30%)** | Adiciona pontuação + sinaliza para revisão |
| **Multiple risky counterparties** | Adiciona pontuação + sinaliza para revisão |
| **Medium wallet risk score** | Adiciona pontuação + sinaliza para revisão |
| **Análise pendente** | Retém a transação até a conclusão da análise |

### Campos de análise para regras

A análise de cripto grava estas chaves no `custom_values` da transação, para que as regras possam usá-las como `custom_values.<key>`:

| Campo | Tipo | Descrição |
| - | - | - |
| `sanctions_hit` | boolean | `true` quando a própria carteira é sancionada ou quando os fundos de qualquer uma de suas contrapartes vieram de entidades sancionadas (exposição). Grandes exchanges costumam ser `true` apenas por exposição. |
| `wallet_sanctioned` | boolean | `true` somente quando o provedor de análise atribui a própria carteira analisada a uma entidade sancionada (designações da OFAC, UE, ONU ou HMT). A exposição, por si só, nunca define esse valor. |
| `aml_sanctions_exposure_pct` | number (0-100) | Parcela do volume analisado da carteira que teve contato com entidades sancionadas. É calculada da mesma forma que `aml_high_risk_exposure_pct`, restrita a sanções. |

Use `wallet_sanctioned` para bloquear transferências para uma carteira sancionada sem recusar transferências para grandes exchanges que tenham apenas exposição indireta.
Use `sanctions_hit` ou `aml_sanctions_exposure_pct` para revisar ou pontuar a exposição.

A regra predefinida **Sanctions counterparty** recusa quando `wallet_sanctioned` é `true`, e a regra predefinida **Exposição a sanções** envia para revisão as carteiras que têm apenas exposição.
As duas nunca são aplicáveis à mesma transação, então uma carteira sancionada é sempre recusada.
Se você instalou a **Sanctions counterparty** antes dessa mudança, a Didit a migrou para `wallet_sanctioned` por você e adicionou a **Exposição a sanções** no mesmo modo, de modo que uma transferência que a regra antiga recusava apenas por exposição agora vai para revisão.

Após a conclusão da análise, a Didit reavalia automaticamente todas as regras com os dados enriquecidos da transação e dispara os webhooks aplicáveis.

## Próximos passos

> [card] [Envio de transações](https://docs.didit.me/pt-br/transaction-monitoring/transactions.md)
>
> Como enviar transações, incluindo os detalhes da carteira de criptomoedas.

> [card] [Regras e pontuação](https://docs.didit.me/pt-br/transaction-monitoring/rules.md)
>
> Como os resultados da triagem alimentam o mecanismo de regras.

> [card] [Guia do console](https://docs.didit.me/pt-br/transaction-monitoring/console.md)
>
> Como visualizar no console a análise de triagem de cripto, a origem dos recursos e os grafos de rede.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.