> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockgence.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Screening de una dirección

> Evalúa el riesgo de una dirección en una consulta puntual (no es un monitoreo continuo de transacciones) y
devuelve una recomendación: `allow`, `review` o `block`, con sus razones y sus fuentes. Combina las etiquetas
de blockgence (listas de sanciones, fuentes comunitarias y las etiquetas propias que ve su clave de API o su
caso), la atribución en vivo, las marcas de direcciones maliciosas de GoPlus y el estado de congelamiento por
emisores de stablecoins.

Campos principales:
- `recommendation` y `risk` (`score`, `level` y `reasons`, cada razón con su fuente).
- `label`, `category` y `labels[]`, con la fuente, el método y la confianza de cada etiqueta.
- `known`: `false` si ninguna fuente identifica la dirección. Un `allow` con `known: false` significa que la
 dirección no figura en las fuentes, no que esté revisada y libre de riesgo.
- `sanctions_status`: `sanctioned` (una lista aplicada la incluye hoy), `delisted` (estuvo y fue dada de baja:
 no bloquea ni suma riesgo), `conflict` (tiene una baja, pero la lista vigente la vuelve a incluir) o `null`.
 `sanctions_history` es la línea de tiempo de altas y bajas; en cada evento, `date_precision: entity` indica
 que la fecha es la del alta de la entidad, no la de la dirección.
- `sanctions_lists`: contra qué listas se evaluó (`applied`), las designaciones en listas que su organización
 no eligió (`not_applied`, citadas, sin efecto en la recomendación) y las listas no cargadas (`not_loaded`).
- `issuer_freeze`: si un emisor congeló la dirección, leído en la red a un bloque fijo. Un congelamiento
 vigente sube `allow` a `review`. `frozen: null` significa que no se pudo determinar, no que no esté congelada.
- `malicious_flags`: las marcas de GoPlus. Escalan `allow` a `review`, pero nunca bloquean por sí solas.
- `service_type` (por ejemplo `instant-exchanger` o `privacy-pool`, donde el rastro se corta) y
 `conflicting_tags` (marcas de terceros citadas pero no aplicadas). Ninguno de los dos cambia la
 recomendación.
- `not_covered`: lo que el screening no evalúa en esa red, por diseño.
- `degraded_sources`: las fuentes que no respondieron. Con una falla, la recomendación se calcula con las demás
 y `malicious_flags` vacío no significa «sin marcas».

Solo una sanción vigente produce `block`.

Formatos de dirección: EVM, Tron, Monero (solo red principal), Bitcoin, Litecoin y Solana. En las redes que no
son EVM, la red se deduce del formato, la dirección se envía sin cambiar mayúsculas y solo cuentan las
etiquetas de blockgence, incluidas las listas de sanciones. Una dirección EVM con una red que no corresponde, o
un formato no reconocido, responden `400`.

**Costo:** 3 créditos de base. Algunas operaciones cobran menos si reutilizan un resultado guardado; nunca más.



## OpenAPI

````yaml /openapi.es.json get /v1/screening/{addr}
openapi: 3.1.0
info:
  title: API de blockgence
  description: >-
    La API de **blockgence** da acceso al rastreo de fondos, la atribución de
    entidades y el screening de riesgo

    explicable sobre varias redes, con la evidencia de cada resultado.


    ### Autenticación

    Todas las rutas `/v1/*` requieren una **clave de API**, en el header
    `X-API-Key: <clave>` o en

    `Authorization: Bearer <clave>`. La clave la entrega su organización. Las
    rutas de verificación de evidencia

    (`/v1/evidence/*`) no requieren clave.


    ### Créditos y límites

    Cada plan tiene un **límite de pedidos por minuto** y una **cantidad mensual
    de créditos**. Cada operación indica

    su costo en créditos. **Solo se cobran las respuestas correctas (status
    menor que 400):** una respuesta de error

    queda registrada con 0 créditos. El consumo se consulta en `GET
    /v1/account`.


    ### Datos que no se pudieron leer

    Si la fuente de datos no puede leer lo pedido, la respuesta es `503
    source_unavailable`, sin cobro, con la

    fuente, la red, la consulta, el motivo y si conviene reintentar. Si falla un
    paso intermedio, la respuesta es 200

    y lo declara en `degraded_sources` y en el `coverage_gaps` del nodo o la
    arista: en esos casos, la ausencia de

    datos no significa ausencia de movimientos.


    ### Redes

    `ethereum`, `bsc`, `polygon`, `arbitrum`, `base` y `optimism`; además `tron`
    para rastreo, ficha, fondeo, sondeo

    de redes y transacciones. Qué se puede consultar en cada red se indica en
    `GET /v1/chains`, sin costo. Las redes

    `monero`, `bitcoin`, `litecoin` y `solana` se reconocen en `/screening` y
    `/address`, donde la red se deduce del

    formato de la dirección. Cualquier otra red responde `400`: nunca se
    reemplaza por Ethereum.
  contact:
    name: blockgence
    url: https://www.blockgence.com/
  version: 1.0.0
servers:
  - url: https://app.blockgence.com
    description: Producción
security: []
tags:
  - name: Plataforma
    description: >-
      Qué redes hay, qué se puede consultar en cada una, con qué fuentes y con
      qué metodología. Sin costo.
  - name: Rastreo
    description: >-
      Rastreo del flujo de fondos y lecturas de una dirección o una transacción:
      grafo en los dos sentidos con consistencia temporal, fondeo, contrapartes,
      puentes, swaps, mezcladores, etiquetas y datos on-chain.
  - name: Screening
    description: >-
      Screening de riesgo de una dirección, con una recomendación (allow, review
      o block), sus razones y sus fuentes.
  - name: Contratos
    description: Inspección de contratos y simulación de una transacción antes de firmarla.
  - name: Tokens
    description: >-
      Ficha de un token, con su emisor, su suministro, sus tenedores y sus
      señales de riesgo.
  - name: Compromiso
    description: >-
      Vector de compromiso de una billetera robada, es decir, cómo se perdió el
      control de los fondos.
  - name: Incidentes
    description: >-
      Respuesta a incidentes de víctimas, hackeos y estafas: playbook, pedidos
      de congelamiento a emisores, post-mortem y entregables.
  - name: Copiloto
    description: >-
      Copiloto de investigación con IA, que responde en lenguaje natural y cita
      la evidencia (streaming SSE).
  - name: Casos
    description: >-
      Casos de investigación para guardar, compartir y exportar, con su
      evidencia, su actividad y sus anotaciones.
  - name: Permisos
    description: >-
      Aprobaciones, delegaciones y firmas que dan acceso a los fondos de una
      dirección (ERC-20, Permit2 y EIP-7702).
  - name: Guard
    description: >-
      Vigilancia de billeteras y protocolos, con alertas por webhook y por
      correo.
  - name: Travel Rule
    description: >-
      Travel Rule sin conexión con terceros: desafío de titularidad,
      contraparte, conciliación y validación de mensajes IVMS101.
  - name: Auditoría
    description: >-
      Auditoría de smart contracts, con el estado, los hallazgos y la evidencia
      de cada auditoría.
  - name: Evidencia
    description: >-
      Verificación de la evidencia sellada, con la clave pública de firma y los
      sellos de tiempo. No requiere clave de API ni cobra.
  - name: Monero
    description: >-
      Ficha pública de una transacción de Monero y verificación de una prueba de
      pago. Monero no publica remitentes ni montos, por lo que no se rastrea.
  - name: Cuenta
    description: Consumo y límites de su clave de API.
  - name: Íconos
    description: Logos de entidades para mostrar grafos en su propia interfaz. Sin costo.
  - name: Servicio
    description: Estado del servicio.
paths:
  /v1/screening/{addr}:
    get:
      tags:
        - Screening
      summary: Screening de una dirección
      description: >-
        Evalúa el riesgo de una dirección en una consulta puntual (no es un
        monitoreo continuo de transacciones) y

        devuelve una recomendación: `allow`, `review` o `block`, con sus razones
        y sus fuentes. Combina las etiquetas

        de blockgence (listas de sanciones, fuentes comunitarias y las etiquetas
        propias que ve su clave de API o su

        caso), la atribución en vivo, las marcas de direcciones maliciosas de
        GoPlus y el estado de congelamiento por

        emisores de stablecoins.


        Campos principales:

        - `recommendation` y `risk` (`score`, `level` y `reasons`, cada razón
        con su fuente).

        - `label`, `category` y `labels[]`, con la fuente, el método y la
        confianza de cada etiqueta.

        - `known`: `false` si ninguna fuente identifica la dirección. Un `allow`
        con `known: false` significa que la
         dirección no figura en las fuentes, no que esté revisada y libre de riesgo.
        - `sanctions_status`: `sanctioned` (una lista aplicada la incluye hoy),
        `delisted` (estuvo y fue dada de baja:
         no bloquea ni suma riesgo), `conflict` (tiene una baja, pero la lista vigente la vuelve a incluir) o `null`.
         `sanctions_history` es la línea de tiempo de altas y bajas; en cada evento, `date_precision: entity` indica
         que la fecha es la del alta de la entidad, no la de la dirección.
        - `sanctions_lists`: contra qué listas se evaluó (`applied`), las
        designaciones en listas que su organización
         no eligió (`not_applied`, citadas, sin efecto en la recomendación) y las listas no cargadas (`not_loaded`).
        - `issuer_freeze`: si un emisor congeló la dirección, leído en la red a
        un bloque fijo. Un congelamiento
         vigente sube `allow` a `review`. `frozen: null` significa que no se pudo determinar, no que no esté congelada.
        - `malicious_flags`: las marcas de GoPlus. Escalan `allow` a `review`,
        pero nunca bloquean por sí solas.

        - `service_type` (por ejemplo `instant-exchanger` o `privacy-pool`,
        donde el rastro se corta) y
         `conflicting_tags` (marcas de terceros citadas pero no aplicadas). Ninguno de los dos cambia la
         recomendación.
        - `not_covered`: lo que el screening no evalúa en esa red, por diseño.

        - `degraded_sources`: las fuentes que no respondieron. Con una falla, la
        recomendación se calcula con las demás
         y `malicious_flags` vacío no significa «sin marcas».

        Solo una sanción vigente produce `block`.


        Formatos de dirección: EVM, Tron, Monero (solo red principal), Bitcoin,
        Litecoin y Solana. En las redes que no

        son EVM, la red se deduce del formato, la dirección se envía sin cambiar
        mayúsculas y solo cuentan las

        etiquetas de blockgence, incluidas las listas de sanciones. Una
        dirección EVM con una red que no corresponde, o

        un formato no reconocido, responden `400`.


        **Costo:** 3 créditos de base. Algunas operaciones cobran menos si
        reutilizan un resultado guardado; nunca más.
      operationId: screening_route_v1_screening__addr__get
      parameters:
        - name: addr
          in: path
          required: true
          schema:
            type: string
            title: Addr
          description: >-
            Dirección a evaluar: EVM (`0x` y 40 caracteres hexadecimales), Tron
            (`T…`), Monero, Bitcoin, Litecoin o Solana. Las direcciones que no
            son EVM se envían tal cual, respetando mayúsculas. Otro formato
            responde `400`.
        - name: chain
          in: query
          required: false
          schema:
            type: string
            title: Chain
            default: ethereum
          description: >-
            Red a consultar para una dirección EVM (ver `GET /v1/chains`). Valor
            por defecto: `ethereum`. En las demás familias, la red se deduce del
            formato de la dirección. Una dirección `3…`, válida en Bitcoin y en
            Litecoin, se evalúa en Litecoin solo con `chain=litecoin`.
        - name: X-Case-Id
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Case-Id
          description: >-
            Caso activo, opcional: el token de un caso que usted puede ver. La
            consulta queda registrada en ese caso y usa también sus etiquetas
            propias. Un caso que no existe, se borró o ya no está compartido con
            usted responde `400 case_unavailable` y la consulta no se hace, sin
            cobro.
      responses:
        '200':
          description: >-
            La recomendación, el riesgo, las etiquetas y la cobertura del
            screening.
          content:
            application/json:
              schema: {}
        '401':
          description: Falta la clave de API, o es inválida o revocada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Se agotaron los créditos del mes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: >-
            El pedido no tiene la forma esperada; `detail` indica qué campo
            corregir.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: >-
            Se superó el límite de pedidos por minuto. Reintente después de los
            segundos que indica `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: >-
            `source_unavailable`: la fuente de datos no pudo leer lo pedido. No
            se cobran créditos. Si falla un paso intermedio, la respuesta es 200
            y lo declara en `degraded_sources`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceUnavailable'
      security:
        - APIKeyHeader: []
        - BearerAuth: []
components:
  schemas:
    Error:
      type: object
      title: Error
      description: >-
        Forma común de los errores: un `detail` legible y, en muchos casos, un
        `error` con un código estable para reconocerlo sin interpretar el texto.
      properties:
        detail:
          type: string
          description: Qué ocurrió, en una frase.
        error:
          type: string
          description: Código estable del error, cuando lo tiene.
      required:
        - detail
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SourceUnavailable:
      type: object
      title: SourceUnavailable
      description: >-
        La fuente de datos no pudo leer lo pedido. No se cobran créditos. La
        ausencia de datos no indica que la dirección esté libre de riesgo ni que
        no tenga movimientos.
      properties:
        error:
          type: string
          enum:
            - source_unavailable
        detail:
          type: string
          description: Qué falló, dónde y si conviene reintentar.
        source:
          type: string
          description: >-
            Fuente que no pudo responder, por ejemplo `etherscan` o
            `blockscout`.
        chain:
          type: string
        primitive:
          type: string
          description: Lectura de blockgence que no se completó.
        operation:
          type: string
          description: Consulta concreta a la fuente.
        target:
          type: string
          description: Lo consultado (dirección o transacción), abreviado.
        reason:
          type: string
          description: >-
            Motivo estable, por ejemplo `rate_limited`, `timeout` o
            `upstream_error`.
        retryable:
          type: boolean
        http_status:
          type:
            - integer
            - 'null'
        retry_after:
          type:
            - integer
            - 'null'
          description: >-
            Segundos que conviene esperar antes de reintentar; también llega en
            el header `Retry-After`.
        upstream_message:
          type:
            - string
            - 'null'
        source_fault:
          type: boolean
          description: Si la falla fue de la fuente o de un límite propio de la consulta.
        failure_cause:
          type: string
          description: Causa de la falla, en una frase.
      required:
        - error
        - detail
        - source
        - reason
        - retryable
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: Su clave de API en el header `X-API-Key`.
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        La misma clave de API en `Authorization: Bearer <clave>`, como
        alternativa a `X-API-Key`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.