> ## 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 screening de wallets y criptomonedas

> Didit analiza wallets y hashes de transacciones con puntuación de riesgo, exposición y grafos de red. Screening de wallets desde $0.15 por consulta.

Para las transacciones con criptomonedas, Didit puede analizar direcciones de wallets y hashes de transacción con proveedores de análisis de blockchain como Merkle Science, Crystal, Chainalysis, Elliptic y TRM Labs al crear la transacción. El análisis se ejecuta en el servidor, así que no necesitas hacer llamadas adicionales a la API.

> [!TIP]
>
> ¿Necesitas analizar una dirección **sin** una transacción? Usa el endpoint de [análisis de wallets bajo demanda](https://docs.didit.me/es/transaction-monitoring/wallet-screening.md) (`POST /v3/wallet-screening/`) para obtener el mismo resultado de riesgo para una sola wallet con una única llamada a la API.

## Cuándo se activa el análisis

El análisis cripto se ejecuta automáticamente cuando se cumplen ambas condiciones:

1. La transacción tiene `currency_kind: "crypto"` en los detalles de la transacción
2. La monitorización de transacciones está habilitada en la [configuración de tu aplicación](https://docs.didit.me/es/transaction-monitoring/settings.md)

Puedes sobrescribir este valor predeterminado en cada transacción con `include_crypto_screening` en el payload de creación de la transacción:

| Valor | Comportamiento |
| - | - |
| `true` | Ejecuta el análisis cripto aunque el valor predeterminado de la aplicación esté deshabilitado |
| `false` | Omite el análisis cripto aunque el valor predeterminado de la aplicación esté habilitado |
| omitido o `null` | Usa el valor predeterminado de la aplicación configurado en la consola |

> [!TIP]
>
> El valor predeterminado de la aplicación se encuentra en **Transacciones** > **Configuración** en la Business Console. `include_crypto_screening` solo sobrescribe ese valor predeterminado para la transacción concreta que estás creando.

## Selección del activo y la red

El activo y la red son campos independientes.
Asigna a `transaction_details.currency` el símbolo del token, a `transaction_details.currency_kind` el valor `crypto` y a `transaction_details.crypto_params.crypto_chain` la red.
Por ejemplo, este fragmento registra un token personalizado en Base:

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

El análisis gestionado acepta `BTC`, `ETH`, `LTC`, `XRP`, `BCH`, `DOGE`, `TRX`, `SOL`, `MATIC`, `BNB`, `BASE`, `OP`, `ARB`, `AVAX`, `ADA`, `XLM` y `HBAR`.
`BASE` corresponde a Base, `OP` a Optimism, `ARB` a Arbitrum One, `AVAX` a Avalanche C-Chain, `ADA` a Cardano, `XLM` a Stellar y `HBAR` a Hedera.
También se aceptan los nombres habituales de las redes, por ejemplo `POLYGON` o `POL` para `MATIC`, `BSC` para `BNB` y `TRON` para `TRX`.
Celo, Mode y Plume no están cubiertas por la integración gestionada; se analizan a través de una cuenta de TRM Labs conectada (`CELO`, `MODE`, `PLUME`).
Los proveedores conectados tienen su propia cobertura; Lightning tiene requisitos adicionales que se describen más abajo.

Especifica siempre `crypto_chain` para un token, incluidos USDT y USDC.
Sin este campo, la moneda se usa como red, y USDT y USDC toman la red del hash de la transacción o, si no hay hash, de la dirección de la wallet.
Un hash de Tron o de Solana selecciona Tron o Solana.
Un hash con prefijo `0x` tiene el mismo formato en todas las redes EVM, así que para USDT, USDC y ETH Didit lo busca en Ethereum, BNB Chain, Polygon, Base, Arbitrum y Optimism, y analiza la transacción en la red donde lo encuentra.
ETH se incluye porque es nativo en Ethereum, Base, Arbitrum y Optimism, y también se transfiere en BNB Chain como token BEP-20 puenteado.
Si ninguna red tiene el hash, o no se pueden consultar las redes en ese momento, la transacción no se analiza y el análisis no se cobra.
En ese caso, `custom_values.aml_screening_status` es `FAILED`, `custom_values.aml_screening_error` indica el motivo y una transacción aprobada pasa a revisión.

En una transacción de USDT o USDC sin hash, se analiza una wallet y la dirección de la wallet selecciona la red.
Una dirección de Tron se analiza en Tron y una dirección de Solana en Solana.
Una dirección `0x` se analiza en la primera red, entre Ethereum, BNB Chain, Polygon, Base, Arbitrum y Optimism, en la que haya enviado una transacción o tenga el token.
Una dirección `0x` sin actividad en ninguna de ellas, o cuyas redes no se puedan consultar en ese momento, se analiza en Ethereum.

Enviar `crypto_chain` evita esta búsqueda.
Nunca uses `ETH` en lugar de la red real.

Registrar un símbolo de token personalizado no garantiza que sus transferencias estén indexadas para el análisis por hash de transacción.
La cobertura de un token debe comprobarse con el contrato del token y la red.
Que una transacción se haya creado no demuestra que el análisis se haya completado correctamente: revisa el estado del análisis y el resultado del proveedor antes de considerarla analizada.

## Entrante frente a saliente

`transaction_details.direction` es obligatorio porque indica a Didit qué lado de la transferencia debe analizarse.

| Dirección | Antes de la transferencia on-chain | Después de la transferencia on-chain |
| - | - | - |
| **Entrante** (depósitos) | Analiza la wallet emisora de la contraparte, si la proporcionas en `counterparty.payment_method.account_id` | Analiza el hash de la transacción asociado a la dirección de depósito de tu servicio o cliente en `subject.payment_method.account_id` |
| **Saliente** (retiros) | Analiza la wallet de destino en `counterparty.payment_method.account_id` antes de enviar los fondos | Analiza el hash de la transacción asociado a la misma wallet de destino en `counterparty.payment_method.account_id` |

Para el análisis previo a la transferencia, omite `transaction_details.payment_reference_id`; Didit ejecuta un análisis de wallet sobre la dirección de wallet correspondiente. Para el análisis posterior a la transferencia, incluye el hash de la transacción en blockchain en `transaction_details.payment_reference_id`; Didit ejecuta un análisis de la transacción y guarda un resumen de sus datos cuando el enriquecimiento on-chain está disponible.

### Lightning Network

Asigna `LIGHTNING` a `transaction_details.crypto_params.crypto_chain` para analizar transacciones de Lightning Network.
El análisis de Lightning requiere un proveedor BYOK de Elliptic o Chainalysis conectado en el **Marketplace** de la consola.
Las integraciones gestionadas de Merkle Science, Crystal y TRM Labs no aceptan `LIGHTNING`; Didit rechaza esas solicitudes con `400` antes de realizar el análisis o facturar.

Con Elliptic, Didit analiza el identificador de Lightning proporcionado mediante el análisis de wallets BTC Lightning de Elliptic.
Con Chainalysis, Didit envía una transferencia de Lightning a KYT cuando `transaction_details.payment_reference_id` está presente.

## Campos obligatorios

En todas las solicitudes de análisis cripto, envía:

* `transaction_details.direction` — `INBOUND` o `OUTBOUND`
* `transaction_details.currency_kind` — `crypto`
* `transaction_details.currency` — el símbolo del activo, por ejemplo `BTC`, `ETH`, `USDC` o tu token personalizado
* Una dirección de wallet en el participante indicado por las reglas de dirección anteriores

Para el análisis por hash de transacción, una vez que la transferencia está on-chain, envía también:

* `transaction_details.payment_reference_id` — el hash de la transacción en la blockchain

Si el análisis cripto está activado y falta la dirección de wallet correspondiente a la dirección de la transacción, la API Create Transaction rechaza la solicitud.

## Ejemplo: análisis saliente antes de la transferencia

Antes de enviar fondos, crea una transacción cripto saliente sin hash de transacción. Didit analiza la wallet 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..."
    }
  }
}
```

## Ejemplo: análisis entrante posterior a la transferencia

Después de recibir fondos, incluye el hash de la transacción. Didit analiza el hash de la transacción en relación con tu dirección de depósito y, cuando está disponible, añade a la respuesta información resumida de la transacción.

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

## Proveedores compatibles

| Proveedor | Estado | Precio gestionado | Precio con clave conectada |
| - | - | - | - |
| **Merkle Science** | Disponible | \$0.15/análisis | \$0.02/análisis |
| **Crystal** | Conecta una clave del proveedor desde Marketplace | No disponible | \$0.02/análisis |
| **Chainalysis** | Conecta una clave del proveedor desde Marketplace | No disponible | \$0.02/análisis |
| **Elliptic** | Conecta una clave del proveedor desde Marketplace | No disponible | \$0.02/análisis |
| **TRM Labs** | Conecta una clave del proveedor desde Marketplace | No disponible | \$0.02/análisis |

Configura tu proveedor preferido en **Transactions** > **Settings** > **Provider Preferences** en la [Business Console](https://business.didit.me), o conecta tu propia clave del proveedor desde **Marketplace** en la consola (categoría Crypto monitoring).

`LIGHTNING` solo es compatible con las configuraciones de Chainalysis y Elliptic con clave conectada.

> [!TIP]
>
> Con el **precio con clave conectada**, conectas una clave de API existente de un proveedor y pagas la tarifa de infraestructura indicada por cada análisis. Usa esta opción si ya tienes un acuerdo comercial con un proveedor de análisis de blockchain.

## Resultados del análisis

Cada análisis produce un resultado estandarizado, sea cual sea el proveedor utilizado.

### Estado del análisis

`custom_values.aml_screening_status` indica si una transacción se analizó.

| Valor | Significado |
| - | - |
| `COMPLETED` | El análisis terminó. El resultado está en `provider_results` y en los demás campos de análisis de `custom_values`. |
| `PENDING` | El análisis aún no ha terminado: el proveedor todavía lo está procesando, o Didit vuelve a analizar el hash de la transacción más tarde (ver más abajo). |
| `ERROR` | El proveedor respondió, pero informó de que su propio análisis falló. |
| `FAILED` | La transacción no se analizó. `custom_values.aml_screening_error` indica el motivo. El análisis gestionado por Didit no cobra nada por ello; una solicitud que haya respondido tu proveedor conectado cuenta como una solicitud al proveedor. |

Una transacción que, de otro modo, se aprobaría pasa a `IN_REVIEW` mientras su análisis esté en cualquier estado distinto de `COMPLETED`.

### Hashes de transacción aún no indexados

Un proveedor de analítica de blockchain puede tardar unos minutos en indexar una transferencia que se acaba de minar y, hasta entonces, no puede analizarla.
Cuando el proveedor responde que aún no ha indexado un hash de transacción, y la propia red confirma que la transacción existe, Didit vuelve a analizarla en segundo plano en lugar de darla por fallida:

* La respuesta de creación ya muestra `custom_values.aml_screening_status` como `PENDING`, con el motivo en `custom_values.aml_screening_error`.
  Una transacción aprobada queda retenida en `IN_REVIEW` con `decision_reason_code` `aml_screening_pending`.
* Didit vuelve a analizar el hash de la transacción unos 2, 12 y 42 minutos después de que se creara la transacción.
* Cuando un reintento logra analizarla, el resultado se guarda como cualquier otro análisis y el análisis se cobra una sola vez.
  Tus reglas se ejecutan de nuevo sobre los datos del análisis, se libera la retención y recibes un único webhook `transaction.status.updated` con el estado que tiene la transacción después de aplicar las reglas, haya cambiado o no.
  Una transacción que, mientras tanto, se haya rechazado o que un revisor haya resuelto conserva su estado.
* Si el proveedor sigue sin haber indexado el hash de la transacción después del último reintento, el análisis termina en `FAILED` igual que habría terminado en la creación: la transacción permanece en `IN_REVIEW` con `decision_reason_code` `aml_screening_failed`, y se cobra como se cobraría un fallo en la creación: nada en el análisis gestionado por Didit, y una solicitud al proveedor cuando el último intento llegó a tu proveedor conectado. Los intentos anteriores que se reintentaron nunca se cobran.
* Si tu saldo ya no alcanza para cubrir el análisis cuando se ejecuta un reintento, el análisis termina en `FAILED` y no se cobra nada.

Los reintentos se aplican a hashes de transacción en Ethereum, BNB Chain, Polygon, Base, Arbitrum, Optimism y Tron.
Un hash que su red no conoce, o un hash de otra red, no se reintenta: el análisis falla de inmediato.

### Puntuación de riesgo y severidad

Cada wallet o transacción analizada recibe:

* **Puntuación de riesgo** (0–100): las puntuaciones más altas indican una mayor exposición a entidades de riesgo
* **Nivel de severidad**: se deriva de la puntuación: `LOW`, `MEDIUM`, `HIGH` o `CRITICAL`

### Análisis del origen de los fondos

Un desglose porcentual de la procedencia de los fondos, clasificado por tipo de entidad:

| Categoría | Nivel de riesgo | Descripción |
| - | - | - |
| `SANCTIONED` | Crítico | Entidades incluidas en listas de sanciones internacionales (OFAC, UE, ONU) |
| `TERRORIST_FINANCING` | Crítico | Direcciones vinculadas a la financiación del terrorismo |
| `CHILD_EXPLOITATION` | Crítico | Direcciones vinculadas a material de explotación infantil |
| `RANSOMWARE` | Alto | Direcciones de pago de ransomware |
| `STOLEN_FUNDS` | Alto | Direcciones asociadas a robos o hackeos conocidos |
| `DARKNET_MARKET` | Alto | Direcciones de mercados de la darknet |
| `MIXER` | Alto | Servicios de mezcla (mixing o tumbling) utilizados para ocultar el origen de los fondos |
| `SCAM` | Alto | Direcciones conocidas de estafas o fraudes |
| `HIGH_RISK_EXCHANGE` | Medio | Exchanges con controles KYC/AML deficientes |
| `HIGH_RISK_JURISDICTION` | Medio | Entidades en jurisdicciones de alto riesgo incluidas en las listas del GAFI (FATF) |
| `GAMBLING_UNLICENSED` | Medio | Plataformas de apuestas sin licencia |
| `P2P_EXCHANGE` | Bajo | Servicios de intercambio entre pares (peer-to-peer) |
| `EXCHANGE` | Bajo | Exchanges de criptomonedas regulados |
| `UNNAMED_SERVICE` | Bajo | Servicios no identificados |

Cada entidad del desglose incluye el porcentaje de los fondos, los importes recibidos y enviados, y si la conexión es directa o indirecta.

### Tabla de exposición

Una tabla de exposición que muestra las entidades de origen, de destino y de contraparte, con:

* Nombre y categoría de la entidad
* Conexión directa o indirecta (distancia en saltos)
* Importes recibidos y enviados
* Nivel de riesgo de cada entidad

### Grafo de red

Una representación visual de nodos y aristas de las relaciones transaccionales de la wallet:

* Los **nodos** representan wallets, exchanges, servicios y otras entidades
* Las **aristas** representan transacciones entre nodos, con importes y hashes de transacción
* Las **métricas** incluyen estadísticas a nivel de grafo, como la centralidad y la profundidad

El grafo de red está disponible en la [Business Console](https://docs.didit.me/es/transaction-monitoring/console.md) como visualización interactiva.

## Integración con reglas

Los resultados del análisis alimentan directamente el [motor de reglas](https://docs.didit.me/es/transaction-monitoring/rules.md). Didit incluye reglas predefinidas que se activan automáticamente en función de los datos del análisis:

| Regla predefinida | Acción |
| - | - |
| **Sanctions counterparty** | Rechazo inmediato: la propia wallet analizada se atribuye a una entidad sancionada (`custom_values.wallet_sanctioned`) |
| **Exposición a sanciones** | Sumar puntuación + marcar para revisión: la wallet movió fondos hacia o desde entidades sancionadas sin estar sancionada ella misma (`sanctions_hit` verdadero, `wallet_sanctioned` no verdadero) |
| **Terrorist financing / child exploitation** | Rechazo inmediato |
| **Darknet market exposure** | Sumar puntuación + marcar para revisión |
| **Mixer/obfuscation service exposure** | Sumar puntuación + marcar para revisión |
| **High-risk source of funds (>30%)** | Sumar puntuación + marcar para revisión |
| **Multiple risky counterparties** | Sumar puntuación + marcar para revisión |
| **Medium wallet risk score** | Sumar puntuación + marcar para revisión |
| **Análisis pendiente** | Retener la transacción hasta que finalice el análisis |

### Campos del análisis para reglas

El análisis de criptomonedas escribe estas claves en el `custom_values` de la transacción, de modo que las reglas pueden usarlas como `custom_values.<key>`:

| Campo | Tipo | Descripción |
| - | - | - |
| `sanctions_hit` | booleano | `true` cuando la propia wallet está sancionada o cuando los fondos de cualquiera de sus contrapartes provienen de entidades sancionadas (exposición). Es habitual que los grandes exchanges sean `true` solo por exposición. |
| `wallet_sanctioned` | booleano | `true` solo cuando el proveedor del análisis atribuye la propia wallet analizada a una entidad sancionada (designaciones de OFAC, la UE, la ONU o HMT). La exposición por sí sola nunca lo activa. |
| `aml_sanctions_exposure_pct` | número (0-100) | Proporción del volumen analizado de la wallet que estuvo en contacto con entidades sancionadas. Se calcula como `aml_high_risk_exposure_pct`, limitado a sanciones. |

Usa `wallet_sanctioned` para bloquear transferencias a una wallet sancionada sin rechazar transferencias a grandes exchanges que solo tienen exposición indirecta.
Usa `sanctions_hit` o `aml_sanctions_exposure_pct` para revisar o puntuar la exposición.

La regla predefinida **Sanctions counterparty** rechaza cuando `wallet_sanctioned` es `true`, y la regla predefinida **Exposición a sanciones** envía a revisión las wallets que solo tienen exposición.
Las dos nunca coinciden en la misma transacción, por lo que una wallet sancionada siempre se rechaza.
Si instalaste **Sanctions counterparty** antes de este cambio, Didit la actualizó para usar `wallet_sanctioned` por ti y añadió **Exposición a sanciones** en el mismo modo, de modo que una transferencia que la regla anterior rechazaba solo por exposición ahora pasa a revisión.

Cuando finaliza el análisis, Didit vuelve a evaluar automáticamente todas las reglas con los datos enriquecidos de la transacción y dispara los webhooks que correspondan.

## Próximos pasos

> [card] [Envío de transacciones](https://docs.didit.me/es/transaction-monitoring/transactions.md)
>
> Cómo enviar transacciones con los datos de la wallet de criptomonedas.

> [card] [Reglas y puntuación](https://docs.didit.me/es/transaction-monitoring/rules.md)
>
> Cómo los resultados del análisis alimentan el motor de reglas.

> [card] [Guía de la consola](https://docs.didit.me/es/transaction-monitoring/console.md)
>
> Consulta en la consola el análisis de criptomonedas, el origen de los fondos y los grafos de red.


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