> ## 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.

# Aportar una etiqueta privada

> Guarda una etiqueta privada sobre una dirección EVM. Sin `X-Case-Id`, la etiqueta es de su clave de API (o de su
usuario, desde la app); con `X-Case-Id`, del caso. Solo la ven los pedidos con ese alcance, nunca otros clientes.

**Cuerpo del pedido.** Un objeto `Label` con `address` (`0x` + 40 hex), `chain`, `label`, `category`, `source`
y `confidence`. Para que una etiqueta aportada no se presente como otra fuente, el servidor fija o limita estos
campos:
- `added_by` y `method` se guardan siempre como `"user"` y `"heuristic"`.
- `source` se guarda como `"usuario: <texto>"`, en una línea y con hasta 200 caracteres.
- `confidence`: número entre 0 y 1 (por defecto 0.5), guardado con un máximo de 0.5, por debajo de cualquier
 otra fuente.
- `category`: `bridge`, `contract`, `darknet`, `exchange`, `mixer`, `scam`, `unknown` o `victim`. `sanctioned`
 y `ex_sanctioned` están reservadas: una sanción proviene solo de las listas oficiales.
- `service_type`, `conflicting_tags` y `sanctions_history` se guardan vacíos.

**Respuesta.** `{"ok": true, "address": …, "label": {…}, "scope": {…}}`, con la etiqueta tal como quedó guardada
y el alcance con que se guardó.

**Errores.** `400` si la dirección no es EVM, si la categoría está reservada o no es válida, si `confidence`
está fuera de rango, o si `X-Case-Id` no corresponde a un caso que usted pueda editar (la etiqueta no se guarda).
`422` si un campo no tiene la forma esperada.

**Costo:** 1 crédito.



## OpenAPI

````yaml /openapi.es.json post /v1/labels
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/labels:
    post:
      tags:
        - Rastreo
      summary: Aportar una etiqueta privada
      description: >-
        Guarda una etiqueta privada sobre una dirección EVM. Sin `X-Case-Id`, la
        etiqueta es de su clave de API (o de su

        usuario, desde la app); con `X-Case-Id`, del caso. Solo la ven los
        pedidos con ese alcance, nunca otros clientes.


        **Cuerpo del pedido.** Un objeto `Label` con `address` (`0x` + 40 hex),
        `chain`, `label`, `category`, `source`

        y `confidence`. Para que una etiqueta aportada no se presente como otra
        fuente, el servidor fija o limita estos

        campos:

        - `added_by` y `method` se guardan siempre como `"user"` y
        `"heuristic"`.

        - `source` se guarda como `"usuario: <texto>"`, en una línea y con hasta
        200 caracteres.

        - `confidence`: número entre 0 y 1 (por defecto 0.5), guardado con un
        máximo de 0.5, por debajo de cualquier
         otra fuente.
        - `category`: `bridge`, `contract`, `darknet`, `exchange`, `mixer`,
        `scam`, `unknown` o `victim`. `sanctioned`
         y `ex_sanctioned` están reservadas: una sanción proviene solo de las listas oficiales.
        - `service_type`, `conflicting_tags` y `sanctions_history` se guardan
        vacíos.


        **Respuesta.** `{"ok": true, "address": …, "label": {…}, "scope": {…}}`,
        con la etiqueta tal como quedó guardada

        y el alcance con que se guardó.


        **Errores.** `400` si la dirección no es EVM, si la categoría está
        reservada o no es válida, si `confidence`

        está fuera de rango, o si `X-Case-Id` no corresponde a un caso que usted
        pueda editar (la etiqueta no se guarda).

        `422` si un campo no tiene la forma esperada.


        **Costo:** 1 crédito.
      operationId: add_label_v1_labels_post
      parameters:
        - name: X-Case-Id
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Case-Id
          description: >-
            Caso al que se agrega la etiqueta, opcional: el token de un caso que
            usted puede editar. Sin este header, la etiqueta queda para su clave
            de API. Un caso que no existe o que usted no puede editar responde
            `400` y la etiqueta no se guarda.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Label'
      responses:
        '200':
          description: Respuesta correcta.
          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:
    Label:
      properties:
        address:
          type: string
          title: Address
        chain:
          type: string
          title: Chain
          default: ethereum
        label:
          type: string
          title: Label
        category:
          type: string
          title: Category
          default: unknown
        source:
          type: string
          title: Source
          default: ''
        confidence:
          type: number
          title: Confidence
          default: 0.5
        method:
          type: string
          title: Method
          default: heuristic
        added_by:
          type: string
          title: Added By
          default: seed
        service_type:
          anyOf:
            - type: string
              enum:
                - instant-exchanger
                - privacy-pool
                - deposit-address
            - type: 'null'
          title: Service Type
        conflicting_tags:
          items:
            $ref: '#/components/schemas/ConflictingTag'
          type: array
          title: Conflicting Tags
        sanctions_history:
          items:
            $ref: '#/components/schemas/SanctionsEvent'
          type: array
          title: Sanctions History
        chain_basis:
          anyOf:
            - $ref: '#/components/schemas/LabelChainBasis'
            - type: 'null'
        entity:
          anyOf:
            - $ref: '#/components/schemas/EntityRef'
            - type: 'null'
        observed_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Observed At
        observed_basis:
          anyOf:
            - type: string
              enum:
                - source_row
                - source_snapshot
                - source_commit
                - measured
                - analyst
                - none
            - type: 'null'
          title: Observed Basis
        valid_until:
          anyOf:
            - type: string
            - type: 'null'
          title: Valid Until
        validity:
          anyOf:
            - type: string
              enum:
                - not_declared
                - ended
                - live
            - type: 'null'
          title: Validity
        license:
          anyOf:
            - $ref: '#/components/schemas/LabelLicense'
            - type: 'null'
      type: object
      required:
        - address
        - label
      title: Label
    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
    ConflictingTag:
      properties:
        name:
          type: string
          title: Name
        slug:
          type: string
          title: Slug
          default: ''
        tag_type:
          type: string
          title: Tag Type
          default: ''
        category:
          type: string
          title: Category
          default: ''
        source:
          type: string
          title: Source
          default: blockscout
        applied:
          type: boolean
          title: Applied
          default: false
        reason:
          type: string
          title: Reason
          default: ''
      type: object
      required:
        - name
      title: ConflictingTag
      description: >-
        Tag de riesgo de un tercero que la clasificación NO aplicó a la
        `category`.


        Glass-box estructurado: antes estos tags viajaban solo como texto libre
        dentro de

        `Label.source` y el cliente no podía leerlos como dato. Caso típico: la
        hot wallet de

        FixedFloat trae los genéricos «Phish / Hack» y «Poisoning Address» junto
        al nombre de

        la entidad — el tag de identidad gana (`exchange`), pero el conflicto se
        muestra.

        NO mueve `category`, `risk.score` ni la recomendación: es contexto para
        ponderar.
    SanctionsEvent:
      properties:
        authority:
          type: string
          title: Authority
        list:
          type: string
          title: List
        programs:
          items:
            type: string
          type: array
          title: Programs
        action:
          type: string
          enum:
            - listed
            - delisted
          title: Action
        date:
          anyOf:
            - type: string
            - type: 'null'
          title: Date
        date_precision:
          type: string
          enum:
            - address
            - entity
            - unknown
          title: Date Precision
          default: unknown
        source_url:
          type: string
          title: Source Url
        entity:
          type: string
          title: Entity
          default: ''
        ref:
          type: string
          title: Ref
          default: ''
        as_of:
          anyOf:
            - type: string
            - type: 'null'
          title: As Of
        note:
          type: string
          title: Note
          default: ''
      type: object
      required:
        - authority
        - list
        - action
        - source_url
      title: SanctionsEvent
      description: >-
        Un hecho fechado de una lista de sanciones sobre una dirección: alta
        (`listed`) o baja

        (`delisted`), con la autoridad, la lista, los programas y la fuente que
        lo publica.


        Glass-box: hasta el 2026-09-18 el historial viajaba como texto dentro de
        `Label.source` y el

        front lo recuperaba con regex. `date_precision` dice QUÉ se fechó: OFAC
        publica en

        SDN_ADVANCED la fecha de alta de la ENTIDAD, no de cada dirección
        (Lazarus Group entró el

        2019-09-13 y la dirección de Ronin recién en la Recent Action del
        2022-04-14), así que esa fecha

        es `entity` y no se puede leer como «la dirección está designada desde
        ese día».


        Lo llenan solo las fuentes de sanciones: el seed de la lista OFAC
        vigente

        (`attribution/ofac_sdn.py`) y el registro de bajas
        (`attribution/sanctions.py`). Una label de

        usuario nunca lo trae (`labels._as_user_label` lo vacía).
    LabelChainBasis:
      properties:
        origin_chain:
          type: string
          title: Origin Chain
        applied_chain:
          type: string
          title: Applied Chain
        basis:
          type: string
          enum:
            - same_key
            - designation
            - not_applied
          title: Basis
        account_type:
          type: string
          title: Account Type
          default: ''
        key_chain:
          type: string
          title: Key Chain
          default: ''
        measured_block:
          anyOf:
            - type: integer
            - type: 'null'
          title: Measured Block
        measured_at:
          type: string
          title: Measured At
          default: ''
        note:
          type: string
          title: Note
          default: ''
      type: object
      required:
        - origin_chain
        - applied_chain
        - basis
      title: LabelChainBasis
      description: >-
        Por qué una label publicada para OTRA chain (`origin_chain` =
        `Label.chain`) aparece en la chain

        de la consulta (`applied_chain`). Lo pone el server al leer el índice
        (`labels.for_chain`); ninguna

        fuente ni cliente lo escribe. Sin este campo, la label es de la misma
        chain de la consulta (o de

        usuario, que vale en toda chain).
         • `same_key`: la address es una EOA medida (tiene clave), y la clave es la misma en toda chain
         EVM: la label se aplica acá como INFERENCIA declarada, con su categoría.
         • `designation`: la lista OFAC designa la address (y sus bajas la fechan): vale en toda chain EVM.
         • `not_applied`: contrato, cuenta sin prueba de clave o sin medir en su origen: en esta chain la
         misma address puede ser otra cosa, así que la label viaja como `context` (peso 0) y el nodo toma
         nombre y categoría de su propia chain.
    EntityRef:
      properties:
        id:
          type: string
          title: Id
        brand:
          type: string
          title: Brand
        kind:
          type: string
          title: Kind
          default: exchange
        countries:
          items:
            type: string
          type: array
          title: Countries
        registrations:
          items:
            $ref: '#/components/schemas/EntityRegistration'
          type: array
          title: Registrations
        basis:
          type: string
          enum:
            - label_name
            - registry_address
          title: Basis
          default: label_name
        note:
          type: string
          title: Note
          default: ''
      type: object
      required:
        - id
        - brand
      title: EntityRef
      description: >-
        La entidad regional a la que pertenece la MARCA de una label (ver el
        bloque de arriba).
    LabelLicense:
      properties:
        name:
          type: string
          title: Name
        spdx:
          type: string
          title: Spdx
          default: ''
        status:
          type: string
          enum:
            - ok
            - restricted
            - pending_review
            - not_licensed
          title: Status
        commercial_use:
          type: string
          title: Commercial Use
        packaged:
          type: boolean
          title: Packaged
          default: true
        url:
          type: string
          title: Url
          default: ''
        as_of:
          type: string
          title: As Of
          default: ''
      type: object
      required:
        - name
        - status
        - commercial_use
      title: LabelLicense
      description: >-
        La licencia de la FUENTE de una label (registro
        `attribution/provenance.py`, por `added_by`): qué licencia es,

        si permite el uso comercial y si el dato va en un entregable. None en la
        label = no consta.
    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
    EntityRegistration:
      properties:
        country:
          type: string
          title: Country
        registry:
          type: string
          title: Registry
        registry_name:
          type: string
          title: Registry Name
          default: ''
        number:
          anyOf:
            - type: integer
            - type: 'null'
          title: Number
        legal_name:
          type: string
          title: Legal Name
          default: ''
        trade_name:
          type: string
          title: Trade Name
          default: ''
        tax_id:
          type: string
          title: Tax Id
          default: ''
        registered_at:
          type: string
          title: Registered At
          default: ''
        status:
          type: string
          enum:
            - listed
            - not_listed
          title: Status
          default: listed
        basis:
          items:
            type: string
          type: array
          title: Basis
        checked_at:
          type: string
          title: Checked At
          default: ''
        source_url:
          type: string
          title: Source Url
          default: ''
        review:
          type: string
          title: Review
          default: ''
      type: object
      required:
        - country
        - registry
      title: EntityRegistration
      description: >-
        Una inscripción de la marca en un registro público (hoy: Registro de
        PSAV de la CNV, Argentina).
  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.