> ## 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.

# Triagem de carteiras e endereços cripto (API KYT)

> A Didit faz a triagem de carteiras e hashes de transação para risco AML: pontuação de risco, exposição e sanções. Desde $0.15 por verificação.

A triagem de carteiras de criptoativos da Didit, também chamada triagem de endereços ou KYT (conheça a sua transação), verifica os endereços de carteiras e os hashes de transação de cada transferência de criptoativos quanto ao risco de AML e devolve uma pontuação de risco, a exposição a fontes de risco e eventuais correspondências com sanções.

Para transações com criptoativos, a Didit pode submeter endereços de carteiras e hashes de transação à análise de fornecedores de análise de blockchain como Merkle Science, Crystal, Chainalysis, Elliptic e TRM Labs durante a criação da transação. A triagem é executada do lado do servidor, sem necessidade de chamadas adicionais à API da sua parte.

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

## Como funciona a triagem

A triagem cripto é executada automaticamente quando se verificam ambas as condições:

1. A transação tem `currency_kind: "crypto"` nos respetivos detalhes
2. A monitorização de transações está ativada nas suas [definições da aplicação](https://docs.didit.me/pt/transaction-monitoring/settings.md)

Pode substituir este valor predefinido por transação com `include_crypto_screening` no payload do pedido de criação de transação:

| Valor | Comportamento |
| - | - |
| `true` | Executar a triagem cripto mesmo que o valor predefinido ao nível da aplicação esteja desativado |
| `false` | Não executar a triagem cripto mesmo que o valor predefinido ao nível da aplicação esteja ativado |
| omitido ou `null` | Usar o valor predefinido ao nível da aplicação configurado na Console |

> [!TIP]
>
> O valor predefinido ao nível da aplicação encontra-se em **Transações** > **Definições** na Business Console. `include_crypto_screening` substitui esse valor apenas para a transação individual que está a criar.

## 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 fragmento regista um token personalizado na Base:

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

A triagem gerida 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.
Também são aceites nomes comuns de redes, por exemplo `POLYGON` ou `POL` para `MATIC`, `BSC` para `BNB` e `TRON` para `TRX`.
Celo, Mode e Plume não estão abrangidas pela integração gerida; são submetidas a triagem através de uma conta TRM Labs ligada (`CELO`, `MODE`, `PLUME`).
A cobertura dos fornecedores ligados depende de cada um; o Lightning tem requisitos adicionais, indicados abaixo.

Indique sempre `crypto_chain` para um token, incluindo USDT e USDC.
Sem este campo, a moeda é usada como rede, e o USDT e o USDC obtêm a rede a partir do hash da transação ou, na falta de hash, a partir do endereço da carteira.
Um hash da Tron ou da Solana seleciona a rede Tron ou a rede Solana.
Um hash `0x` é igual em todas as redes EVM, por isso, para USDT, USDC e ETH, a Didit procura-o na Ethereum, BNB Chain, Polygon, Base, Arbitrum e Optimism e faz a triagem da transação na rede onde o encontrar.
O ETH está incluído porque é nativo na Ethereum, Base, Arbitrum e Optimism e também é transferido na BNB Chain como token BEP-20 em ponte.
Se nenhuma rede tiver o hash, ou se as redes não puderem ser verificadas naquele momento, a transação não é submetida a triagem e a triagem não é faturada.
Nesse caso, `custom_values.aml_screening_status` é `FAILED`, `custom_values.aml_screening_error` indica o motivo e uma transação aprovada passa para revisão.

Uma transação de USDT ou USDC sem hash submete uma carteira à triagem, e o endereço da carteira seleciona a rede.
Um endereço da Tron é submetido à triagem na rede Tron e um endereço da Solana é submetido à triagem na rede Solana.
Um endereço `0x` é submetido à triagem na primeira das redes Ethereum, BNB Chain, Polygon, Base, Arbitrum e Optimism onde tenha enviado uma transação ou detenha o token.
Um endereço `0x` sem atividade em nenhuma dessas redes, ou cujas redes não possam ser verificadas naquele momento, é submetido à triagem na rede Ethereum.

Enviar `crypto_chain` evita a pesquisa.
Nunca substitua `ETH` pela rede real.

Registar um símbolo de token personalizado não garante que as suas transferências estejam indexadas para triagem por hash de transação.
A cobertura do token deve ser verificada com base no contrato do token e na rede.
Uma transação criada não é prova de triagem bem-sucedida: verifique o estado da triagem e o resultado do fornecedor antes de a considerar submetida à triagem.

## Recebida vs enviada

`transaction_details.direction` é obrigatório, porque indica à Didit qual dos lados da transferência deve ser submetido a triagem.

| Direção | Antes da transferência on-chain | Depois da transferência on-chain |
| - | - | - |
| **Recebida** (depósitos) | Faça a triagem da carteira do remetente da contraparte, se a indicar em `counterparty.payment_method.account_id` | Faça a triagem do hash da transação, limitado ao endereço de depósito do seu serviço ou cliente, em `subject.payment_method.account_id` |
| **Enviada** (levantamentos) | Faça a triagem da carteira de destino em `counterparty.payment_method.account_id` antes de enviar fundos | Faça a triagem do hash da transação, limitado à 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 de carteiras sobre o endereço relevante. Para a triagem após a transferência, inclua o hash da transação blockchain em `transaction_details.payment_reference_id`; a Didit executa a triagem da transação e guarda os dados resumidos 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 Lightning requer um fornecedor BYOK Elliptic ou Chainalysis associado no **Marketplace** da consola.
Merkle Science, Crystal e TRM Labs geridos não aceitam `LIGHTNING`; a Didit rejeita esses pedidos com `400` antes da triagem ou da faturação.

Para a Elliptic, a Didit faz a triagem do identificador Lightning fornecido através da análise de carteiras BTC Lightning da Elliptic.
Para a Chainalysis, a Didit submete uma transferência Lightning ao KYT quando `transaction_details.payment_reference_id` está presente.

## Campos obrigatórios

Para todos os pedidos de triagem 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 o seu token personalizado
* Um endereço de carteira no participante selecionado pelas regras de direção acima

Para a triagem do hash da transação depois de a transferência estar on-chain, envie também:

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

Se a triagem cripto estiver ativada e o endereço exigido para a direção estiver em falta, a API Create Transaction rejeita o pedido.

## Exemplo: triagem de saída antes da transferência

Antes de enviar fundos, crie uma transação cripto enviada sem hash de transação. A Didit faz a triagem da 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: triagem de entrada depois da transferência

Depois de receber fundos, inclua o hash da transação. A Didit faz a triagem do hash da transação, limitado ao seu endereço de depósito, e enriquece a resposta com informação resumida da transação quando estiver disponível.

```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"
  }
}
```

## Fornecedores suportados

| Fornecedor | Estado | Preços geridos | Preços com chave associada |
| - | - | - | - |
| **Merkle Science** | Disponível | \$0.15/triagem | \$0.02/triagem |
| **Crystal** | Ligue uma chave de fornecedor através do Marketplace | Não disponível | \$0.02/triagem |
| **Chainalysis** | Ligue uma chave de fornecedor através do Marketplace | Não disponível | \$0.02/triagem |
| **Elliptic** | Ligue uma chave de fornecedor através do Marketplace | Não disponível | \$0.02/triagem |
| **TRM Labs** | Ligue uma chave de fornecedor através do Marketplace | Não disponível | \$0.02/triagem |

Configure o fornecedor de sua preferência em **Transações** > **Definições** > **Preferências de fornecedores** na [Business Console](https://business.didit.me), ou ligue a sua própria chave de fornecedor a partir do **Marketplace** da consola (categoria Monitorização de criptomoedas).

`LIGHTNING` é suportado apenas por configurações Chainalysis e Elliptic com chave associada.

> [!TIP]
>
> Com **preços com chave associada**, associa uma chave de API de fornecedor existente e paga a taxa de infraestrutura indicada por triagem. Use esta opção quando já tiver um acordo comercial com um fornecedor de análise de blockchain.

## Resultados da triagem

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

### Estado da triagem

`custom_values.aml_screening_status` indica se uma transação foi submetida a triagem.

| Valor | Significado |
| - | - |
| `COMPLETED` | A triagem terminou. O resultado está em `provider_results` e nos outros campos de triagem de `custom_values`. |
| `PENDING` | A triagem ainda não terminou: o fornecedor continua a analisar a transação ou a Didit volta a fazer a triagem do hash da transação mais tarde (ver abaixo). |
| `ERROR` | O fornecedor respondeu, mas indicou que a sua própria análise falhou. |
| `FAILED` | A transação não foi submetida a triagem. `custom_values.aml_screening_error` indica o motivo. A triagem gerida pela Didit não é cobrada; um pedido a que o seu fornecedor ligado respondeu conta como um pedido ao fornecedor. |

Uma transação que, de outra forma, seria aprovada passa para `IN_REVIEW` enquanto o estado da triagem for diferente de `COMPLETED`.

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

Um fornecedor de análise de blockchain pode demorar alguns minutos a indexar uma transferência que acabou de ser minerada e, até lá, não a consegue submeter a triagem.
Quando o fornecedor indica que ainda não indexou um hash de transação, e a própria rede confirma que a transação existe, a Didit volta a fazer a triagem em segundo plano, em vez de a dar como falhada:

* A resposta da criação já mostra `custom_values.aml_screening_status` como `PENDING`, com o motivo em `custom_values.aml_screening_error`.
  Uma transação aprovada fica retida em `IN_REVIEW` com `decision_reason_code` `aml_screening_pending`.
* A Didit volta a fazer a triagem do hash da transação cerca de 2, 12 e 42 minutos depois de a transação ser criada.
* Quando uma nova tentativa realiza a triagem, o resultado é guardado como qualquer outra triagem e a triagem é cobrada uma vez.
  As suas regras são executadas novamente com os dados da triagem, a retenção é libertada e recebe um webhook `transaction.status.updated` com o estado que a transação tem após as regras, tenha ou não mudado.
  Uma transação que tenha sido recusada ou resolvida por um revisor entretanto mantém o seu estado.
* Se o fornecedor ainda não tiver indexado o hash da transação após a última tentativa, a triagem termina como `FAILED`, tal como aconteceria na criação: a transação permanece em `IN_REVIEW` com `decision_reason_code` `aml_screening_failed` e é cobrada como seria cobrada uma falha na criação: nada na triagem gerida pela Didit e um pedido ao fornecedor quando a última tentativa chegou ao seu fornecedor ligado. As tentativas anteriores que foram repetidas nunca são cobradas.
* Se o seu saldo deixar de cobrir a triagem quando uma nova tentativa for executada, a triagem termina como `FAILED` e nada é cobrado.

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

### Pontuação de risco e gravidade

Cada carteira ou transação submetida a triagem recebe:

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

### Análise da origem dos fundos

Uma decomposição percentual de onde os fundos tiveram origem, categorizada por tipo de entidade:

| Categoria | Nível de risco | Descrição |
| - | - | - |
| `SANCTIONED` | Crítico | Entidades em listas internacionais de sanções (OFAC, EU, UN) |
| `TERRORIST_FINANCING` | Crítico | Endereços ligados ao financiamento do terrorismo |
| `CHILD_EXPLOITATION` | Crítico | Endereços ligados a material de exploração infantil |
| `RANSOMWARE` | Alto | Endereços de pagamento de ransomware |
| `STOLEN_FUNDS` | Alto | Endereços associados a roubos ou ataques informáticos conhecidos |
| `DARKNET_MARKET` | Alto | Endereços de mercados da darknet |
| `MIXER` | Alto | Serviços de mistura ou de ofuscação utilizados para ocultar a origem dos fundos |
| `SCAM` | Alto | Endereços conhecidos de fraude ou burla |
| `HIGH_RISK_EXCHANGE` | Médio | Plataformas de câmbio com controlos KYC/AML fracos |
| `HIGH_RISK_JURISDICTION` | Médio | Entidades em jurisdições de alto risco listadas pelo FATF |
| `GAMBLING_UNLICENSED` | Médio | Plataformas de jogo sem licença |
| `P2P_EXCHANGE` | Baixo | Serviços de câmbio entre pares |
| `EXCHANGE` | Baixo | Plataformas de câmbio de criptomoedas reguladas |
| `UNNAMED_SERVICE` | Baixo | Serviços não identificados |

Cada entidade na decomposição inclui a percentagem dos fundos, os montantes recebidos e enviados, e se a ligação é direta ou indireta.

### Tabela de exposição

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

* Nome e categoria da entidade
* Ligação direta ou indireta (distância em saltos)
* Montantes recebidos e enviados
* Nível de risco por entidade

### Grafo de rede

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

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

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

## Integração com regras

Os resultados da análise alimentam diretamente o [motor de regras](https://docs.didit.me/pt/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 |
| - | - |
| **Contraparte sancionada** | Recusa imediata - a própria carteira analisada é atribuída a uma entidade sancionada (`custom_values.wallet_sanctioned`) |
| **Exposição a sanções** | Adicionar pontuação e sinalizar para revisão - a carteira movimentou fundos de ou para entidades sancionadas sem ser ela própria sancionada (`sanctions_hit` verdadeiro, `wallet_sanctioned` não verdadeiro) |
| **Financiamento do terrorismo / exploração infantil** | Recusa imediata |
| **Exposição a mercados da darknet** | Adicionar pontuação e sinalizar para revisão |
| **Exposição a serviços de mistura ou ofuscação** | Adicionar pontuação e sinalizar para revisão |
| **Origem dos fundos de risco elevado (>30%)** | Adicionar pontuação e sinalizar para revisão |
| **Múltiplas contrapartes arriscadas** | Adicionar pontuação e sinalizar para revisão |
| **Pontuação de risco da carteira de nível médio** | Adicionar pontuação e sinalizar para revisão |
| **Análise pendente** | Reter a transação até a análise ser concluída |

### Campos de análise para regras

A análise de criptomoedas escreve estas chaves no `custom_values` da transação, para que as regras as possam usar como `custom_values.<key>`:

| Campo | Tipo | Descrição |
| - | - | - |
| `sanctions_hit` | booleano | `true` quando a própria carteira está sancionada, ou quando qualquer parte dos fundos das suas contrapartes teve origem em entidades sancionadas (exposição). As grandes plataformas de câmbio de criptomoedas costumam ficar com `true` apenas por exposição. |
| `wallet_sanctioned` | booleano | `true` apenas quando o fornecedor da 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 o define. |
| `aml_sanctions_exposure_pct` | número (0-100) | Proporção do volume da carteira sujeito a análise que teve contacto com entidades sancionadas. É calculado como `aml_high_risk_exposure_pct`, mas limitado às sanções. |

Use `wallet_sanctioned` para bloquear transferências para uma carteira sancionada, sem recusar transferências para grandes plataformas de câmbio de criptomoedas que tenham apenas exposição indireta.
Use `sanctions_hit` ou `aml_sanctions_exposure_pct` para rever ou pontuar a exposição.

A regra predefinida **Contraparte sancionada** recusa quando `wallet_sanctioned` é `true`, e a regra predefinida **Exposição a sanções** envia para revisão as carteiras cuja única condição é a exposição.
As duas nunca correspondem à mesma transação, pelo que uma carteira sancionada é sempre recusada.
Se instalou a regra **Contraparte sancionada** antes desta alteração, a Didit moveu-a para `wallet_sanctioned` por si e adicionou a **Exposição a sanções** no mesmo modo, pelo que uma transferência que a regra antiga recusava apenas por exposição passa agora para revisão.

Depois de concluída a análise, a Didit volta a avaliar automaticamente todas as regras com os dados da transação enriquecidos e aciona quaisquer webhooks aplicáveis.

## Próximos passos

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

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

> [card] [Guia da consola](https://docs.didit.me/pt/transaction-monitoring/console.md)
>
> Visualizar a análise da triagem de criptomoedas, a origem dos fundos e os grafos de rede na consola.


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