Scan Risk

Analiza el riesgo de una o múltiples direcciones de blockchain en tiempo real, detectando patrones sospechosos y generando puntajes de riesgo.

Cumplimiento Regulatorio

Este endpoint es fundamental para el cumplimiento de regulaciones como GAFI, Regla de Viajes, Ley Fintech de México y LFPIORPI.

---

Endpoint

POST /v1/projects/{projectId}/addresses/scan-risk

---

Autenticación

Header	Formato
x-api-key	ApiKey {tu-api-key}

---

Parámetros de Ruta

Parámetro	Tipo	Descripción
projectId	string	ID del proyecto

---

Request Body

{
    "addresses": [
        {
            "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
            "chainId": "1"
        }
    ],
    "maxDepth": 3,
    "skipExisting": true
}

Campos

Campo	Tipo	Requerido	Default	Descripción
addresses	array	Sí	-	Lista de direcciones a analizar (1-50)
addresses[].address	string	Sí	-	Dirección de wallet (mínimo 10 caracteres)
addresses[].chainId	string	Sí	-	ID de la blockchain
maxDepth	number	No	3	Profundidad del análisis de grafo (1-7)
skipExisting	boolean	No	true	Omitir direcciones ya analizadas

Chains Soportadas

Consulta el endpoint Chains para obtener la lista completa de blockchains habilitadas y sus chainId.

---

Response

{
    "success": true,
    "data": {
        "summary": {
            "total": 1,
            "completed": 1,
            "skipped": 0,
            "failed": 0,
            "duration": 50758
        },
        "results": [
            {
                "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
                "chainId": "1",
                "status": "completed",
                "analysisId": "600f2937-2c54-445d-900d-4bffa69982f5",
                "riskScore": 5,
                "riskLevel": "minimal",
                "riskReason": "Normal activity, no suspicious patterns detected",
                "suspiciousActivity": false,
                "patterns": [],
                "transactionGraph": {
                    "rootAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
                    "totalNodes": 1107,
                    "totalEdges": 2000,
                    "maxDepth": 3
                },
                "analysisEvidence": {
                    "transactionsAnalyzed": 2000,
                    "uniqueAddressesFound": 1107,
                    "analysisDuration": 44950
                }
            }
        ]
    }
}

Campos de Response

Campo	Tipo	Descripción
status	string	Estado del análisis: completed, skipped, failed
analysisId	string	UUID único del análisis
riskScore	number	Puntuación de riesgo (0-100)
riskLevel	string	Nivel de riesgo: minimal, low, medium, high, critical
riskReason	string	Explicación del nivel de riesgo
suspiciousActivity	boolean	Indica si se detectó actividad sospechosa
patterns	array	Patrones de riesgo detectados (wash trading, mixing, etc.)
transactionGraph	object	Información del grafo de transacciones
analysisEvidence	object	Evidencia y métricas del análisis

Niveles de Riesgo

Nivel	Score	Descripción
minimal	0-19	Sin indicadores de riesgo
low	20-39	Actividad normal con mínimas alertas
medium	40-59	Requiere revisión manual
high	60-79	Alta probabilidad de actividad sospechosa
critical	80-100	Conexión directa con actividades ilícitas

---

Ejemplo

curl -X POST "https://api.wavynode.com/v1/projects/{projectId}/addresses/scan-risk" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ApiKey wavy_xxxxx" \
  -d '{
    "addresses": [
      {
        "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
        "chainId": "1"
      }
    ],
    "maxDepth": 3
  }'

---

Errores

Código	Mensaje	Descripción
400	Invalid body	El body no cumple con el schema requerido
401	The api key is invalid	API key inválida o no proporcionada
403	Forbidden	Sin permisos suficientes (requiere rol Developer)
500	Internal server error	Error interno del servidor

---

Patrones Detectados

El análisis puede identificar los siguientes patrones de riesgo:

Patrón	Descripción
wash_trading	Transacciones artificiales para simular volumen
mixing	Uso de servicios de mezcla para ocultar origen de fondos
peel_chain	Cadenas de transacciones para fragmentar fondos
round_tripping	Fondos que regresan al origen tras múltiples saltos
exchange_hopping	Movimiento entre múltiples exchanges para evadir detección