> ## 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 análisis de wallets: AML cripto bajo demanda
> Didit analiza el riesgo AML de una dirección de wallet cripto sin crear transacción: origen de los fondos, sanciones y riesgo. Desde $0.02.
Prompt de la API de análisis de wallets
Copiar el prompt al portapapeles
\
\`Screen a single crypto wallet address for AML risk through the Didit Management API, without creating a transaction.
Endpoint:
POST https://verification.didit.me/v3/wallet-screening/
Authentication:
Use the x-api-key header with my Didit API key.
Goal:
\- Run on-demand AML screening on one crypto address and return a normalised risk result (risk_score, severity, sanctions_hit, source/destination of funds, counterparty connections). Nothing is written to the transactions table.
When to call:
\- Before onboarding a customer's deposit/withdrawal wallet, to pre-check exposure.
\- Any time you need a standalone risk read on an address and do NOT have (or do not want to record) a transaction.
\- For transaction-coupled monitoring instead, use POST /v3/transactions/ with currency_kind = "crypto".
Prerequisites:
\- Transaction monitoring must be configured for the application with a managed provider or an existing provider key. Otherwise the call returns 409.
Request body (application/json):
\{
"wallet_address": "0x94f1b9b64e2932f6a2db338f616844400cd58e8a", // required; alias: address
"blockchain": "ETH", // required; one of BTC, ETH, LTC, XRP, BCH, DOGE, TRX, SOL, MATIC, BNB, BASE, OP, ARB, AVAX, ADA, XLM, HBAR, USDT, USDC, or a common network name such as POLYGON or BSC; alias: currency
"direction": "inbound" // optional; inbound | outbound | deposit | withdrawal
}
Example call:
curl -X POST "https://verification.didit.me/v3/wallet-screening/" \
-H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"wallet_address":"0x94f1b9b64e2932f6a2db338f616844400cd58e8a","blockchain":"ETH"}'
What to read from the response:
\- risk_score (0-100, higher = riskier) and severity (UNKNOWN | LOW | MEDIUM | HIGH | CRITICAL).
\- sanctions_hit (boolean) and dominant_risk_category.
\- source_of_funds / destination_of_funds / counterparty_connections for the exposure breakdown.
Billing:
\- One AML monitoring usage is billed per successful screening. Sandbox applications are not billed.
Failure modes:
\- 400 - malformed wallet address, missing wallet_address, or unsupported blockchain.
\- 401 - missing or malformed x-api-key.
\- 409 - no AML provider configured for the application; configure transaction monitoring first.
\- 502 - provider could not complete the screening; retry later.
For automatic, transaction-coupled crypto screening, see /transaction-monitoring/aml-screening.`
\
Pegar en
## OpenAPI
````yaml es/openapi-25.json POST /v3/wallet-screening/
openapi: 3.0.0
info:
version: 3.0.0
title: Didit Verification API
description: API de verificación de identidad. Autentícate con el encabezado x-api-key.
servers:
- url: https://verification.didit.me
security: []
tags: []
paths:
/v3/wallet-screening/:
post:
tags:
- Transactions
summary: Analizar una dirección de wallet
description: >-
Ejecuta un análisis AML bajo demanda para una sola wallet o dirección
cripto sin crear una transacción. Resuelve el proveedor de análisis de
blockchain configurado en tu aplicación, analiza la dirección de forma
síncrona y devuelve el resultado de riesgo normalizado. LIGHTNING solo
está disponible con una conexión BYOK de Elliptic o Chainalysis añadida
a través de Marketplace. No se escribe nada en la tabla de
transacciones. Se factura un uso de monitorización AML por cada análisis
correcto (las aplicaciones sandbox no se facturan).
operationId: screenWallet
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- wallet_address
properties:
wallet_address:
type: string
description: >-
La dirección cripto o el identificador de red que se va a
analizar. Debe corresponder a la red seleccionada (por
ejemplo, una dirección de 40 caracteres hexadecimales con el
prefijo `0x` para cadenas EVM). Alias: `address`.
example: '0x94f1b9b64e2932f6a2db338f616844400cd58e8a'
blockchain:
type: string
description: >-
Identificador de red opcional. Si se omite, la red se deduce
del formato de la dirección: las direcciones `bc1`, `1` y
`3` son de Bitcoin (BTC), las direcciones `T` son de Tron
(TRX) y las claves públicas base58 son de Solana (SOL). Una
dirección `0x` es válida en todas las redes EVM, por lo que,
si se omite `blockchain` para ella, la respuesta es 422 con
las redes candidatas en `candidate_chains`. El análisis
gestionado admite BTC, ETH, LTC, XRP, BCH, DOGE, TRX, SOL,
MATIC, BNB, BASE (Base), OP (Optimism), ARB (Arbitrum One),
AVAX (Avalanche C-Chain), ADA (Cardano), XLM (Stellar) y
HBAR (Hedera). USDT y USDC son alias heredados de Ethereum,
no búsquedas en varias redes. La cobertura de los
proveedores conectados varía. LIGHTNING requiere un
proveedor conectado compatible. CELO (Celo), MODE (Mode) y
PLUME (Plume) se analizan a través de una cuenta de TRM Labs
conectada; el análisis gestionado responde 400 para ellas.
Alias: `currency`.
enum:
- BTC
- LIGHTNING
- ETH
- LTC
- XRP
- BCH
- DOGE
- TRX
- SOL
- MATIC
- BNB
- USDT
- USDC
- BASE
- OP
- ARB
- AVAX
- ADA
- XLM
- HBAR
- CELO
- MODE
- PLUME
example: ETH
direction:
type: string
description: >-
Opcional. Indica si la dirección se analiza como contraparte
entrante (depósito) o saliente (retiro). Acepta `inbound`,
`outbound`, `deposit` o `withdrawal`. Si se omite, se
realiza por defecto un análisis neutro previo a la
transferencia. Este valor se pasa al proveedor solo como
contexto; no cambia el `risk_score` ni la `severity`
devueltos, ni los desgloses
`source_of_funds`/`destination_of_funds`, que siempre se
devuelven ambos independientemente de `direction`. Por
tanto, cambiar u omitir `direction` no requiere volver a
analizar una dirección.
enum:
- inbound
- outbound
- deposit
- withdrawal
example:
wallet_address: '0x94f1b9b64e2932f6a2db338f616844400cd58e8a'
blockchain: ETH
responses:
'200':
description: El resultado normalizado del análisis de wallets.
content:
application/json:
schema:
$ref: '#/components/schemas/WalletScreeningResult'
example:
provider: merklescience
screening_type: WALLET_SCREENING
risk_score: 95
severity: CRITICAL
status: SCREENED
summary: >-
Merkle Science risk: Critical (5/5). SANCTIONS HIT. Dominant
risk: sanctioned. Driven by: the address is attributed to
Sanctions / OFAC (Example Sanctions)
wallet_address: '0x94f1b9b64e2932f6a2db338f616844400cd58e8a'
transaction_hash: null
blockchain: ETH
block_timestamp: null
total_value_usd: null
fee_usd: null
sender_rows: []
receiver_rows: []
transaction_flows: []
transaction_flows_status: null
transaction_flows_error: null
source_of_funds:
- category: sanctioned
percentage: 100
amount_usd: 9813695
entity_name: Example Sanctions
entity_type: Sanctions
entity_subtype: OFAC
hops: null
description: Sanctions / OFAC
is_direct: true
exposure_direction: incoming
exposure_type: direct
provider_entity_id: '118885'
provider_entity_type_id: '30'
provider_entity_subtype_id: '125'
country: ''
raw_amount: null
raw_currency: null
destination_of_funds:
- category: defi
percentage: 84.824453
amount_usd: 7783414.38
entity_name: Example DeFi 7
entity_type: DeFi
entity_subtype: Bridges
hops: null
description: DeFi / Bridges
is_direct: false
exposure_direction: outgoing
exposure_type: indirect
provider_entity_id: '118459'
provider_entity_type_id: '33'
provider_entity_subtype_id: '143'
country: ''
raw_amount: null
raw_currency: null
- category: defi
percentage: 15.175547
amount_usd: 1392494.37
entity_name: Example DeFi 2
entity_type: DeFi
entity_subtype: Yield Aggregator
hops: null
description: DeFi / Yield Aggregator
is_direct: false
exposure_direction: outgoing
exposure_type: indirect
provider_entity_id: '90192'
provider_entity_type_id: '33'
provider_entity_subtype_id: '142'
country: ''
raw_amount: null
raw_currency: null
counterparty_connections:
- entity_name: Example Sanctions
entity_type: Sanctions
entity_subtype: OFAC
risk_level: critical
categories:
- sanctioned
received_usd: null
sent_usd: null
received_hops: null
sent_hops: null
percentage: 0
is_direct: true
country: null
provider_entity_id: null
- entity_name: Example Sanctions
entity_type: Sanctions
entity_subtype: OFAC
risk_level: critical
categories:
- sanctioned
received_usd: null
sent_usd: null
received_hops: null
sent_hops: null
percentage: 0
is_direct: true
country: null
provider_entity_id: null
network_nodes: []
network_edges: []
sanctions_hit: true
pep_counterparty: null
dominant_risk_category: sanctioned
risk_factors:
- source: attribution
category: sanctioned
label: Sanctions / OFAC
entity_name: Example Sanctions
direction: attribution
exposure_type: attribution
amount_usd: null
percentage: 0
is_high_risk: true
description: >-
the address is attributed to Sanctions / OFAC (Example
Sanctions)
- source: exposure
category: sanctioned
label: Sanctions / OFAC
entity_name: Example Sanctions
direction: incoming
exposure_type: direct
amount_usd: 9813695
percentage: 51.679304
is_high_risk: true
description: >-
51.6793% direct incoming exposure to Sanctions / OFAC
(Example Sanctions)
- source: exposure
category: defi
label: DeFi / Bridges
entity_name: Example DeFi 7
direction: outgoing
exposure_type: indirect
amount_usd: 7783414.38
percentage: 40.987766
is_high_risk: false
description: >-
40.9878% indirect outgoing exposure to DeFi / Bridges
(Example DeFi 7)
- source: exposure
category: defi
label: DeFi / Yield Aggregator
entity_name: Example DeFi 2
direction: outgoing
exposure_type: indirect
amount_usd: 1392494.37
percentage: 7.33293
is_high_risk: false
description: >-
7.33293% indirect outgoing exposure to DeFi / Yield
Aggregator (Example DeFi 2)
raw_response:
...: provider-specific details
report_signature:
'400':
description: >-
Error de validación: dirección de wallet mal formada, falta
`wallet_address`, `blockchain` no compatible, `blockchain` omitido
para una dirección cuyo formato no indica ninguna red, o LIGHTNING
sin una conexión BYOK del Marketplace con Elliptic o Chainalysis.
'401':
description: '`x-api-key` ausente o no válido.'
'409':
description: >-
No hay ningún proveedor AML configurado para la aplicación, o el
proveedor configurado aún no admite el análisis de wallets.
Configura primero la monitorización de transacciones.
'422':
description: >-
`blockchain` omitido para una dirección `0x`, que comparten todas
las redes EVM. No se analiza ni se factura nada; vuelve a enviarla
con `blockchain` establecido en uno de los valores de
`candidate_chains`.
content:
application/json:
schema:
type: object
properties:
blockchain:
type: array
items:
type: string
example:
- >-
A 0x address is valid on every EVM chain. Send
blockchain as one of: ETH, BNB, MATIC, BASE, ARB, OP,
CELO, MODE, PLUME.
candidate_chains:
type: array
items:
type: string
example:
- ETH
- BNB
- MATIC
- BASE
- ARB
- OP
- CELO
- MODE
- PLUME
'502':
description: >-
El proveedor AML no pudo completar el análisis. Vuelve a intentarlo
más tarde.
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: curl
label: curl
source: |-
curl -X POST 'https://verification.didit.me/v3/wallet-screening/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"wallet_address": "0x94f1b9b64e2932f6a2db338f616844400cd58e8a",
"blockchain": "ETH"
}'
- lang: python
label: Python
source: |-
from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.wallet_screening.screen(
wallet_address="0x94f1b9b64e2932f6a2db338f616844400cd58e8a",
blockchain="ETH",
)
print(result)
- lang: javascript
label: Node.js
source: |-
import Didit from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await didit.walletScreening.screen({
wallet_address: "0x94f1b9b64e2932f6a2db338f616844400cd58e8a",
blockchain: "ETH",
});
console.log(result);
- lang: go
label: Go
source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.WalletScreening.Screen(ctx, didit.WalletScreeningScreenParams{\n\tWalletAddress: \"0x94f1b9b64e2932f6a2db338f616844400cd58e8a\",\n\tBlockchain: didit.Some(didit.WalletScreeningScreenParamsBlockchain(\"ETH\")),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
- lang: java
label: Java
source: >-
import me.didit.Didit;
import me.didit.types.WalletScreeningScreenParams;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result =
client.walletScreening().screen(WalletScreeningScreenParams.builder()
.walletAddress("0x94f1b9b64e2932f6a2db338f616844400cd58e8a")
.blockchain(WalletScreeningScreenParams.Blockchain.of("ETH"))
.build());
System.out.println(result);
- lang: php
label: PHP
source: |-
walletScreening->screen([
'wallet_address' => '0x94f1b9b64e2932f6a2db338f616844400cd58e8a',
'blockchain' => 'ETH',
]);
print_r($result->toArray());
- lang: ruby
label: Ruby
source: |-
require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.wallet_screening.screen(
wallet_address: "0x94f1b9b64e2932f6a2db338f616844400cd58e8a",
blockchain: "ETH"
)
puts result.to_h
- lang: csharp
label: .NET
source: >-
using System;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await client.WalletScreening.ScreenAsync(new
WalletScreeningScreenParams
{
WalletAddress = "0x94f1b9b64e2932f6a2db338f616844400cd58e8a",
Blockchain = new WalletScreeningScreenParamsBlockchain("ETH"),
});
Console.WriteLine(JsonSerializer.Serialize(result));
components:
schemas:
WalletScreeningResult:
type: object
properties:
provider:
type: string
description: >-
Proveedor que realizó el análisis (p. ej., `merklescience`,
`crystal`).
screening_type:
type: string
enum:
- WALLET_SCREENING
description: Siempre `WALLET_SCREENING` para este endpoint.
risk_score:
type: integer
description: >-
Puntuación de riesgo normalizada de 0 a 100. Un valor más alto
indica una mayor exposición a entidades de riesgo. Merkle Science
califica una dirección de 0 a 5, lo que se corresponde con 0, 15,
35, 55, 75 o 95.
severity:
type: string
enum:
- UNKNOWN
- LOW
- MEDIUM
- HIGH
- CRITICAL
description: >-
Nivel de riesgo derivado de `risk_score`: `0-9` UNKNOWN, `10-39`
LOW, `40-69` MEDIUM, `70-89` HIGH, `90-100` CRITICAL. `UNKNOWN` es
la banda más baja, no un estado aparte sin datos: un `risk_score` de
0 (el caso habitual de una dirección limpia) significa que no hay
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; consulta
el `risk_score`, no solo la banda. Nunca trates `UNKNOWN` como una
calificación afirmativa de riesgo bajo o sin riesgo; no lo muestres
como aprobado.
status:
type: string
enum:
- SCREENED
- PENDING
- ERROR
description: Estado del resultado del análisis.
summary:
type: string
description: Resumen legible del resultado del análisis.
wallet_address:
type: string
description: La dirección analizada, devuelta tal cual.
transaction_hash:
type: string
nullable: true
description: >-
Campo del análisis de transacciones, compartido con la estructura
del resultado. Siempre es `null` en un resultado de análisis de
wallets.
blockchain:
type: string
description: La blockchain que se analizó.
block_timestamp:
type: string
nullable: true
description: >-
Campo del análisis de transacciones, compartido con la estructura
del resultado. Siempre es `null` en un resultado de análisis de
wallets.
total_value_usd:
type: number
nullable: true
description: >-
Campo del análisis de transacciones, compartido con la estructura
del resultado. Siempre es `null` en un resultado de análisis de
wallets.
fee_usd:
type: number
nullable: true
description: >-
Campo del análisis de transacciones, compartido con la estructura
del resultado. Siempre es `null` en un resultado de análisis de
wallets.
sender_rows:
type: array
items:
type: object
description: >-
Campo del análisis de transacciones, compartido con la estructura
del resultado. Siempre está vacío en un resultado de análisis de
wallets.
receiver_rows:
type: array
items:
type: object
description: >-
Campo del análisis de transacciones, compartido con la estructura
del resultado. Siempre está vacío en un resultado de análisis de
wallets.
transaction_flows:
type: array
items:
type: object
description: >-
Campo del análisis de transacciones, compartido con la estructura
del resultado. Siempre está vacío en un resultado de análisis de
wallets.
transaction_flows_status:
type: string
nullable: true
description: >-
Campo del análisis de transacciones, compartido con la estructura
del resultado. Siempre es `null` en un resultado de análisis de
wallets.
transaction_flows_error:
type: string
nullable: true
description: >-
Campo del análisis de transacciones, compartido con la estructura
del resultado. Siempre es `null` en un resultado de análisis de
wallets.
source_of_funds:
type: array
description: >-
De dónde recibió fondos la dirección, atribuido por entidad. Cada
entrada es un desglose de exposición.
items:
type: object
properties:
category:
type: string
description: >-
Categoría de riesgo normalizada, por ejemplo
`exchange_licensed`, `dex`, `defi`, `payment_processor`,
`mixer`, `darknet_market`, `sanctioned`, `stolen_funds`,
`high_risk_exchange`.
percentage:
type: number
description: Proporción de la exposición total del sentido, de 0 a 100.
amount_usd:
type: number
nullable: true
description: Valor en USD atribuido a esta entidad.
entity_name:
type: string
nullable: true
description: >-
Nombre de la entidad atribuida, por ejemplo un exchange, un
mixer o un grupo sancionado.
entity_type:
type: string
nullable: true
description: >-
Tipo de entidad del proveedor (p. ej., `Exchange`, `DeFi`,
`Sanctions`, `Theft`).
entity_subtype:
type: string
nullable: true
description: >-
Subtipo más detallado (p. ej., `Mandatory KYC and AML`,
`OFAC`, `Yield Aggregator`).
hops:
type: integer
nullable: true
description: >-
Número de saltos hasta la entidad (1 para una contraparte
directa), cuando el proveedor lo informa. Siempre `null` para
Merkle Science, que solo informa de si la exposición es
directa o indirecta: usa `exposure_type`.
description:
type: string
nullable: true
description: >-
`entity_type / entity_subtype`, tal como el proveedor etiqueta
la entidad.
is_direct:
type: boolean
description: True cuando `exposure_type` es `direct`.
exposure_direction:
type: string
enum:
- incoming
- outgoing
- connected
description: >-
Si los fondos provinieron de esta entidad (`incoming`) o se
enviaron a ella (`outgoing`).
exposure_type:
type: string
enum:
- direct
- indirect
description: Exposición `direct` (1 salto) o `indirect` (varios saltos).
provider_entity_id:
type: string
nullable: true
description: El identificador propio del proveedor para la entidad.
provider_entity_type_id:
type: string
nullable: true
description: El identificador propio del proveedor para `entity_type`.
provider_entity_subtype_id:
type: string
nullable: true
description: El identificador propio del proveedor para `entity_subtype`.
country:
type: string
nullable: true
description: >-
País principal de la entidad en formato ISO 3166-1 alfa-2.
Vacío o `null` cuando el proveedor no lo conoce.
raw_amount:
type: number
nullable: true
description: >-
Importe en la unidad propia del activo, cuando el proveedor lo
informa.
raw_currency:
type: string
nullable: true
description: Unidad de `raw_amount`, cuando el proveedor la informa.
destination_of_funds:
type: array
description: >-
A dónde envió fondos la dirección, atribuido por entidad. Misma
estructura de elementos que `source_of_funds`, con
`exposure_direction` = `outgoing`.
items:
type: object
properties:
category:
type: string
description: >-
Categoría de riesgo normalizada, por ejemplo
`exchange_licensed`, `dex`, `defi`, `payment_processor`,
`mixer`, `darknet_market`, `sanctioned`, `stolen_funds`,
`high_risk_exchange`.
percentage:
type: number
description: Proporción de la exposición total del sentido, de 0 a 100.
amount_usd:
type: number
nullable: true
description: Valor en USD atribuido a esta entidad.
entity_name:
type: string
nullable: true
description: >-
Nombre de la entidad atribuida, por ejemplo un exchange, un
mixer o un grupo sancionado.
entity_type:
type: string
nullable: true
description: >-
Tipo de entidad del proveedor (p. ej., `Exchange`, `DeFi`,
`Sanctions`, `Theft`).
entity_subtype:
type: string
nullable: true
description: >-
Subtipo más detallado (p. ej., `Mandatory KYC and AML`,
`OFAC`, `Yield Aggregator`).
hops:
type: integer
nullable: true
description: >-
Número de saltos hasta la entidad (1 para una contraparte
directa), cuando el proveedor lo informa. Siempre `null` para
Merkle Science, que solo informa de si la exposición es
directa o indirecta: usa `exposure_type`.
description:
type: string
nullable: true
description: >-
`entity_type / entity_subtype`, tal como el proveedor etiqueta
la entidad.
is_direct:
type: boolean
description: True cuando `exposure_type` es `direct`.
exposure_direction:
type: string
enum:
- incoming
- outgoing
- connected
description: >-
Si los fondos provinieron de esta entidad (`incoming`) o se
enviaron a ella (`outgoing`).
exposure_type:
type: string
enum:
- direct
- indirect
description: Exposición `direct` (1 salto) o `indirect` (varios saltos).
provider_entity_id:
type: string
nullable: true
description: El identificador propio del proveedor para la entidad.
provider_entity_type_id:
type: string
nullable: true
description: El identificador propio del proveedor para `entity_type`.
provider_entity_subtype_id:
type: string
nullable: true
description: El identificador propio del proveedor para `entity_subtype`.
country:
type: string
nullable: true
description: >-
País principal de la entidad en formato ISO 3166-1 alfa-2.
Vacío o `null` cuando el proveedor no lo conoce.
raw_amount:
type: number
nullable: true
description: >-
Importe en la unidad propia del activo, cuando el proveedor lo
informa.
raw_currency:
type: string
nullable: true
description: Unidad de `raw_amount`, cuando el proveedor la informa.
counterparty_connections:
type: array
description: >-
Entidades a las que el proveedor atribuye la dirección analizada. En
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. No tomes decisiones de enrutamiento según `risk_level` o
`is_direct` aquí: 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.
items:
type: object
properties:
entity_name:
type: string
nullable: true
description: Nombre de la entidad atribuida.
entity_type:
type: string
nullable: true
description: Tipo de entidad del proveedor.
entity_subtype:
type: string
nullable: true
description: Subtipo de entidad del proveedor.
risk_level:
type: string
description: >-
En minúsculas y depende del proveedor. Para Merkle Science es
la calificación de riesgo propia de la dirección, de 0 a 5
(`no_risk`, `low`, `medium_low`, `medium`, `high`,
`critical`), elevada a `high` cuando la categoría de la
entidad es de alto riesgo; no es una calificación aparte de la
entidad.
categories:
type: array
items:
type: string
description: Categorías de riesgo normalizadas de la entidad.
received_usd:
type: number
nullable: true
description: USD recibidos de la entidad, cuando el proveedor lo informa.
sent_usd:
type: number
nullable: true
description: USD enviados a la entidad, cuando el proveedor lo informa.
received_hops:
type: integer
nullable: true
description: >-
Saltos hasta la entidad del lado receptor, cuando el proveedor
los informa.
sent_hops:
type: integer
nullable: true
description: >-
Saltos hasta la entidad del lado emisor, cuando el proveedor
los informa.
percentage:
type: number
description: >-
Proporción de la exposición de la dirección, cuando el
proveedor la informa; en caso contrario, 0.
is_direct:
type: boolean
description: >-
Siempre `true` para Merkle Science, cuyas conexiones son
atribuciones y no contrapartes.
country:
type: string
nullable: true
description: País de la entidad, cuando se conoce.
provider_entity_id:
type: string
nullable: true
description: El identificador propio del proveedor para la entidad.
network_nodes:
type: array
items:
type: object
description: >-
Nodos del grafo de exposición para el análisis de transacciones.
Vacíos en un resultado de análisis de wallets.
network_edges:
type: array
items:
type: object
description: >-
Aristas del grafo de exposición para el análisis de transacciones.
Vacías en un resultado de análisis de wallets.
sanctions_hit:
type: boolean
description: >-
True si la dirección tiene exposición directa o indirecta a
sanciones.
pep_counterparty:
type: boolean
description: >-
Exposición como persona expuesta políticamente. `null` cuando no hay
ningún hallazgo de PEP disponible, lo que ocurre hoy en todos los
resultados porque ningún proveedor lo informa; `false` solo ante un
resultado de análisis negativo explícito. No interpretes `null` como
una comprobación de PEP completada.
nullable: true
dominant_risk_category:
type: string
nullable: true
description: >-
Categoría de alto riesgo con mayor peso, o `null` cuando ninguna es
dominante (p. ej., `sanctioned`, `mixer`, `stolen_funds`).
risk_factors:
type: array
description: >-
Explicación ordenada de `risk_score`: qué produjo este veredicto.
Los proveedores califican una dirección según su propio modelo y
devuelven solo un veredicto (Merkle Science devuelve un entero de 0
a 5), por lo que la puntuación por sí sola no permite actuar. Se
ordena primero por alto riesgo y luego por el valor que pasó por
cada factor, con un máximo de los cinco más relevantes;
`source_of_funds` y `destination_of_funds` siempre contienen el
desglose completo. Un `risk_score` alto sin ninguna entrada
`is_high_risk` significa que el proveedor no informó ninguna
coincidencia con sanciones ni con entidades atribuidas y calificó la
dirección únicamente según su propio modelo de exposición; `summary`
lo indica de forma explícita.
items:
type: object
properties:
source:
type: string
enum:
- attribution
- exposure
description: >-
`attribution` es lo que el proveedor dice que es la propia
dirección (su propia etiqueta o clúster); `exposure` es hacia
dónde se movieron realmente sus fondos.
category:
type: string
description: >-
Categoría de riesgo normalizada, con el mismo vocabulario que
el desglose de exposición.
label:
type: string
description: >-
La redacción propia del proveedor para el factor (p. ej.,
`Gambling / Crypto only`), que es lo mismo que verías en la
consola del proveedor.
entity_name:
type: string
nullable: true
description: >-
Entidad atribuida detrás del factor, por ejemplo un sitio de
apuestas o un exchange.
direction:
type: string
enum:
- incoming
- outgoing
- connected
- unknown
- attribution
description: >-
Sentido del flujo de fondos, `attribution` cuando el factor
determinante es la propia etiqueta de la dirección, o
`unknown` cuando el proveedor no indicó un sentido.
exposure_type:
type: string
enum:
- direct
- indirect
- unknown
- attribution
description: >-
`direct` (1 salto) o `indirect` (varios saltos), `attribution`
para la etiqueta propia de la dirección, o `unknown` cuando el
proveedor no indicó a cuántos saltos está la contraparte.
Trata `unknown` como sin clasificar, no como `direct`.
amount_usd:
type: number
format: float
nullable: true
description: Valor en USD atribuido a este factor determinante.
percentage:
type: number
format: float
description: >-
Proporción del volumen analizado TOTAL de la dirección, con
ambos sentidos combinados, a diferencia de `percentage` dentro
de `source_of_funds`/`destination_of_funds`, que se normaliza
por sentido. Es comparable y sumable en toda la lista.
is_high_risk:
type: boolean
description: >-
Si la categoría es una de las que Didit considera de alto
riesgo (`sanctioned`, `mixer`, `stolen_funds`, `ransomware`,
`scam`, `darknet_market`, `terrorist_financing`,
`child_exploitation`, `hacked_exchange`, `high_risk_exchange`,
`seized_funds`).
description:
type: string
description: >-
Representación en una línea del factor determinante, por
ejemplo `9.01% indirect outgoing exposure to Gambling / Crypto
only (Example Gambling)`.
raw_response:
type: object
additionalProperties: true
description: >-
El payload propio del proveedor. Su estructura depende del proveedor
y puede cambiar sin previo aviso: lee los campos normalizados en
lugar de analizarlo.
report_signature:
type: string
description: >-
Firma HMAC-SHA256 opaca sobre este resultado exacto, limitada a tu
aplicación. No tiene significado por sí sola: vuelve a enviar el
cuerpo completo de la respuesta, sin modificar e incluyendo este
campo, a `POST /v3/wallet-screening/pdf/` para generarlo como PDF.
El endpoint de PDF rechaza la solicitud con `400` si falta
`report_signature` o si se editó algún campo firmado (p. ej.,
`risk_score`, `severity`, `sanctions_hit`) antes de reenviarlo.
required:
- provider
- screening_type
- risk_score
- severity
- status
- summary
- wallet_address
- blockchain
- sanctions_hit
- dominant_risk_category
- source_of_funds
- destination_of_funds
- counterparty_connections
- report_signature
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
La clave de API de tu aplicación, que encontrarás en Developers -> API
keys en la Business Console. La clave principal tiene acceso completo.
Una clave con nombre puede tener un alcance limitado: ninguno, lectura o
escritura por recurso, limitada a algunos flujos o a sesiones aprobadas,
a una lista de direcciones IP y a una fecha de caducidad. 401 significa
que la clave es incorrecta, se revocó o expiró; 403 significa que no se
envió ninguna clave, que la clave no tiene acceso a este recurso o
acción, o que la solicitud provino de una dirección fuera de su lista de
IP; 404 en una ruta de sesión significa que la sesión está fuera de los
flujos o estados de la clave. Una clave sin acceso a contenido
multimedia recibe las URL de imágenes, videos y PDF como null, y una
clave sin permiso de escritura en sesiones recibe los enlaces y tokens
de sesión como null. Consulta https://docs.didit.me/console/api-keys.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.