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 devuelve409 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.
Respuesta
La respuesta es el resultado de análisis estandarizado, con la misma estructura que el resultado del proveedorWALLET_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 desource_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.
Ejemplo
Una respuesta real para una dirección incluida en la lista de sanciones de la OFAC, analizada con Merkle Science. Solo se ha acortadoraw_response y se ha sustituido report_signature:
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 (incluidoreport_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.
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.