API de screening de wallets y criptomonedas

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.

¿Necesitas analizar una dirección sin una transacción? Usa el endpoint de análisis de wallets bajo demanda (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:

La transacción tiene currency_kind: "crypto" en los detalles de la transacción
La monitorización de transacciones está habilitada en la configuración de tu aplicación

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

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:

{
  "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.

{
  "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.

{
  "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, 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.

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 como visualización interactiva.

Integración con reglas

Los resultados del análisis alimentan directamente el motor de reglas. 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

Envío de transacciones

Cómo enviar transacciones con los datos de la wallet de criptomonedas.

Reglas y puntuación

Cómo los resultados del análisis alimentan el motor de reglas.

Guía de la consola

Consulta en la consola el análisis de criptomonedas, el origen de los fondos y los grafos de red.

Primeros pasos

Funciones

Referencia

Consola

API de screening de wallets y criptomonedas

Cuándo se activa el análisis

Selección del activo y la red

Entrante frente a saliente

Lightning Network

Campos obligatorios

Ejemplo: análisis saliente antes de la transferencia

Ejemplo: análisis entrante posterior a la transferencia

Proveedores compatibles

Resultados del análisis

Estado del análisis

Hashes de transacción aún no indexados

Puntuación de riesgo y severidad

Análisis del origen de los fondos

Tabla de exposición

Grafo de red

Integración con reglas

Campos del análisis para reglas

Próximos pasos

Envío de transacciones

Reglas y puntuación

Guía de la consola

​Cuándo se activa el análisis

​Selección del activo y la red

​Entrante frente a saliente

​Lightning Network

​Campos obligatorios

​Ejemplo: análisis saliente antes de la transferencia

​Ejemplo: análisis entrante posterior a la transferencia

​Proveedores compatibles

​Resultados del análisis

​Estado del análisis

​Hashes de transacción aún no indexados

​Puntuación de riesgo y severidad

​Análisis del origen de los fondos

​Tabla de exposición

​Grafo de red

​Integración con reglas

​Campos del análisis para reglas

​Próximos pasos

Envío de transacciones

Reglas y puntuación

Guía de la consola

Cuándo se activa el análisis

Selección del activo y la red

Entrante frente a saliente

Lightning Network

Campos obligatorios

Ejemplo: análisis saliente antes de la transferencia

Ejemplo: análisis entrante posterior a la transferencia

Proveedores compatibles

Resultados del análisis

Estado del análisis

Hashes de transacción aún no indexados

Puntuación de riesgo y severidad

Análisis del origen de los fondos

Tabla de exposición

Grafo de red

Integración con reglas

Campos del análisis para reglas

Próximos pasos