Saltar al contenido principal
A veces necesitas comprobar el riesgo AML de una wallet de criptomonedas antes de que exista una transacción que registrar, por ejemplo, cuando un cliente añade una dirección de retiro o cuando tu equipo de cumplimiento quiere revisar una dirección de forma puntual. El endpoint de análisis de wallets bajo demanda analiza una sola dirección y devuelve el resultado de riesgo completo sin crear una transacción. Es la versión independiente del análisis automático de criptomonedas que se ejecuta durante el envío de transacciones. Ambos usan los mismos proveedores de análisis de blockchain y la misma estructura del resultado.

Cuándo usarlo

El análisis de wallets no escribe nada en la tabla de transacciones. Si necesitas que el análisis quede asociado a una transacción monitorizada (con reglas, alertas y webhooks), envía una transacción.

Requisitos previos

La monitorización de transacciones debe estar configurada para la aplicación con un proveedor gestionado o con una clave de proveedor existente. Configúrala en Transacciones > Configuración > Provider Preferences en la Business Console. Si no hay ningún proveedor configurado, el endpoint devuelve 409 Conflict.

Solicitud

POST https://verification.didit.me/v3/wallet-screening/ Autentícate con el encabezado x-api-key.

Cobertura de cadenas

El análisis gestionado admite Base (BASE), Optimism (OP) y Arbitrum One (ARB) tanto para el análisis de wallets como para el de hashes de transacción. Los proveedores conectados pueden tener una cobertura distinta; además, la cadena debe ser compatible con el proveedor y la cuenta que hayas seleccionado. Celo (CELO), Mode (MODE) y Plume (PLUME) se analizan a través de una cuenta de TRM Labs conectada (Marketplace, con tu propia clave); el análisis gestionado no las cubre y responde 400. No envíes ETH para otra red EVM: la misma dirección puede tener actividad y riesgo distintos en cada cadena. Con el análisis gestionado, USDT y USDC son alias heredados de Ethereum, no una búsqueda en todas las redes donde existen esos tokens. Usa el identificador de red (ETH, TRX, SOL, MATIC, BNB, BASE, OP, ARB, AVAX, ADA, XLM, HBAR o, con TRM Labs, CELO, MODE o PLUME) correspondiente a la cadena real de la wallet. Para los tokens de transacciones registradas, mantén el token en transaction_details.currency e indica la red por separado en transaction_details.crypto_params.crypto_chain. Consulta selección de activo y red.
LIGHTNING solo está disponible cuando la aplicación tiene conectado un proveedor BYOK de Elliptic o Chainalysis en el Marketplace de la consola. No está disponible con Merkle Science gestionado ni con Crystal o TRM Labs. Las solicitudes sin un proveedor conectado compatible devuelven 400 y no se analizan ni se cobran.

Respuesta

La respuesta es el resultado de análisis estandarizado, con la misma estructura que el resultado del proveedor WALLET_SCREENING que devuelve el análisis de transacciones.
Cómo se establece severity. severity es la franja de la risk_score normalizada: 0-9 → UNKNOWN, 10-39 → LOW, 40-69 → MEDIUM, 70-89 → HIGH, 90-100 → CRITICAL. UNKNOWN es la franja más baja, no un estado aparte de “sin datos”: risk_score: 0 (el caso habitual de una dirección limpia) significa que el proveedor no devolvió ninguna evaluación adversa, mientras que una puntuación distinta de cero en el rango 1-9 es una señal real pero inferior a LOW, así que lee la propia risk_score y no solo la franja. En cualquier caso, no muestres UNKNOWN como un resultado afirmativo de “limpio” ni como aprobado.direction no cambia el modelo de riesgo. El campo opcional direction se envía al proveedor solo como contexto. No afecta a risk_score, a severity ni a qué listas de desglose se devuelven: tanto source_of_funds como destination_of_funds se devuelven siempre. Por lo tanto, cambiar u omitir direction no obliga a volver a analizar una dirección ya analizada.

Factores de riesgo

risk_factors es la respuesta ordenada a “por qué esta dirección tiene esta puntuación”. Los proveedores califican una dirección con su propio modelo y devuelven solo un veredicto (Merkle Science devuelve un entero de 0-5), así que risk_score por sí sola no permite actuar. Cada entrada nombra un factor determinante. Se ordenan primero por riesgo alto y luego por el valor que circuló a través de cada uno.
Una puntuación alta sin ningún factor is_high_risk es un resultado real y significativo. Significa que el proveedor calificó la dirección con su propio modelo de exposición sin informar de una coincidencia con sanciones, PEP o una entidad atribuida: los factores que sí aparecen son los flujos de fondos que explican la calificación. summary lo indica explícitamente, así que trata estas direcciones como “revisar los flujos”, no como una coincidencia confirmada. risk_factors se limita a los cinco factores determinantes más fuertes; source_of_funds y destination_of_funds siempre contienen el desglose completo.risk_factors es un campo de nivel superior, no un campo anidado. Los resultados analizados antes de que existiera omiten la clave por completo: interprétala como una lista vacía en lugar de suponer que la explicación está vacía.

Desglose de la exposición

Cada entrada de source_of_funds / destination_of_funds describe una entidad con la que la dirección intercambió fondos:

Conexiones con contrapartes

counterparty_connections enumera las entidades a las que el proveedor atribuye la dirección analizada. Con Merkle Science, provienen de las etiquetas de propietario y de usuario de la propia dirección, por lo que la misma entidad puede aparecer dos veces, y no incluyen flujos de fondos: received_usd, sent_usd, received_hops y sent_hops son null, y percentage es 0.0. Consulta los flujos de fondos en source_of_funds y destination_of_funds.
No tomes decisiones de enrutamiento basándote en counterparty_connections[].risk_level ni en counterparty_connections[].is_direct: con Merkle Science, el primero repite la calificación de la propia dirección (consulta risk_score) y el segundo siempre es true. Usa sanctions_hit, dominant_risk_category y risk_factors[].is_high_risk para el veredicto, y exposure_type en source_of_funds / destination_of_funds para saber si la exposición es directa.

Ejemplo

Una respuesta real para una dirección incluida en la lista de sanciones de la OFAC, analizada con Merkle Science. Solo se ha acortado raw_response y se ha sustituido report_signature:
Los ejemplos ilustran la estructura de la respuesta, no un veredicto garantizado para una dirección real. Las puntuaciones de riesgo y la exposición a sanciones dependen de la red seleccionada, de la información de inteligencia vigente y de la política de riesgo configurada. Que una dirección se atribuya a un exchange no implica una puntuación de riesgo de cero: una wallet de un exchange puede tener exposición a sanciones a través de sus flujos de fondos. sanctions_hit: true puede indicar que la propia wallet está sancionada o solo que sus fondos tienen exposición a sanciones, por lo que, por sí solo, no significa que el titular de la wallet analizada esté sancionado. Cuando el mismo análisis se ejecuta sobre una transacción registrada, las reglas también pueden leer custom_values.wallet_sanctioned, que es true solo cuando el proveedor atribuye la propia wallet a una entidad sancionada, y custom_values.aml_sanctions_exposure_pct. Consulta Campos de análisis para reglas. Lee risk_factors, source_of_funds y destination_of_funds para distinguir la atribución de la exposición. Consulta Análisis de criptomonedas y wallets para ver un recorrido paso a paso.

Informe PDF

Para obtener un PDF con la marca de Didit de un resultado de análisis, vuelve a enviar el cuerpo exacto de la respuesta (incluido report_signature) a POST /v3/wallet-screening/pdf/. Es una operación sin estado: no se llama al proveedor, no se factura nada adicional y no se guarda nada. Si modificas cualquier campo firmado (risk_score, severity, sanctions_hit, …) antes de volver a enviarlo, la solicitud falla con 400.
Consulta PDF del análisis de wallets para ver el esquema completo de la solicitud y la respuesta, y la estructura de los errores.

Facturación

Cada análisis completado con éxito se factura como un uso de monitorización AML, a la misma tarifa que el análisis cripto vinculado a transacciones. Consulta los precios para ver las tarifas gestionadas y las de clave conectada. Las aplicaciones de sandbox no se facturan. Los errores de validación (400) y los errores por proveedor no configurado (409) nunca se facturan.

Errores

Próximos pasos

Referencia de la API

Esquema completo de la solicitud y la respuesta del endpoint Screen Wallet.

PDF de Screen Wallet

Genera un PDF con la marca de Didit a partir del resultado de un análisis.

Análisis de criptomonedas y wallets

Análisis automático al crear transacciones y modelo de resultados.
Última modificación el 1 de noviembre de 2026