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

# Registrar un protocolo

> Registra un protocolo y sus contratos en Watchtower. Cada contrato es una vigilancia de Guard con
`purpose: "protocol"` y las reglas del protocolo.

Cuerpo del pedido: `{"name": "…", "chain": "ethereum", "contracts": [{"address": "0x…", "name": "…"}], "rules": {…},
"shared": false, "events": [...]}`.

- `contracts`: de 1 a 50. Cuentan contra el límite de vigilancias del plan. Se registran todos o ninguno.
- `chain`: solo las redes listadas en `watchtower.chains` de `GET /v1/guard/status`.
- `rules`: se combinan con las reglas por defecto (`presets.protocol` en `GET /v1/guard/status`):
 - `large_withdrawal`: lo que sale del contrato en una transacción, neto de lo que entra en la misma
 transacción, en USD y solo con activos con precio. Umbral `min_usd`, por defecto US$1,000,000. Un préstamo
 flash que se devuelve o un swap en un pool no lo alcanzan.
 - `authority_change`: cambio de propietario (owner) o de administrador (admin), y otorgar, quitar o cambiar el
 rol de administración. Con `all_roles: 1`, cualquier rol.
 - `authority_transfer_started`: la propuesta de un propietario o un administrador nuevo en un traspaso en dos
 pasos de OpenZeppelin, antes de que se acepte.
 - `proxy_upgrade`: upgrade del proxy o del beacon.
 - `pause`: pausa y reanudación.
 - `scheduled_change`: una llamada programada en un timelock o una propuesta de un governor registrados como
 contratos del protocolo. Avisa antes de la ejecución, con el efecto de la llamada simulado sobre el estado
 del bloque en que se programó. Ese estado puede cambiar antes de la ejecución, y un revert en la simulación
 no significa que la ejecución vaya a fallar.
 - `protocol_event`: los eventos propios declarados en `events`.
- `events`: opcional, eventos propios a vigilar. Cada uno es
 `{"signature": "Evento(address indexed a, bool b)", "label": "…", "severity": "high", "contracts": ["0x…"]}`.
 `severity` es `high` por defecto, y `contracts` vacío aplica a todos los contratos del protocolo. Para elegirlo
 del ABI verificado, agregue `"source": "abi", "abi_address": "0x…"` (ver
 `GET /v1/guard/protocols/{pid}/abi-events`). Hasta 30 eventos, firmas de hasta 300 caracteres y hasta 3
 parámetros indexados. No se aceptan eventos anónimos, repetidos, de contratos ajenos al protocolo ni los que
 Guard ya lee (los de autoridad, `Transfer`, `Approval`, `ApprovalForAll`, `TransferSingle`, `TransferBatch`,
 `CallScheduled`, `QueueTransaction` y `ProposalCreated`).

Las alertas de autoridad y las de cambios programados de severidad alta o crítica no se pierden por el tope diario
de alertas. Las de eventos propios tienen un tope propio de 50 por contrato y por día. De un contrato se guardan
sus eventos de autoridad y los de las transacciones con alerta, no cada transferencia.

Responde el protocolo creado, con la misma forma que `GET /v1/guard/protocols/{pid}`.

Errores:
- `400`: red no disponible para Watchtower, nombre vacío, cantidad de contratos fuera de 1 a 50, dirección
 inválida o repetida, regla inválida, `shared` sin organización, o un evento inválido (incluido un contrato sin
 código verificado o una firma que no está en su ABI).
- `403`: los contratos superan el límite de vigilancias del plan, o la clave de API no está asignada a una
 persona.
- `404`: Watchtower no está habilitado.
- `409`: uno de los contratos ya está vigilado.
- `422`: el cuerpo del pedido trae un campo desconocido.
- `502`: no se pudo leer el ABI verificado que necesita un evento; `detail.failure` describe la falla.

**Costo:** sin cargo.



## OpenAPI

````yaml /openapi.es.json post /v1/guard/protocols
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/guard/protocols:
    post:
      tags:
        - Guard
      summary: Registrar un protocolo
      description: >-
        Registra un protocolo y sus contratos en Watchtower. Cada contrato es
        una vigilancia de Guard con

        `purpose: "protocol"` y las reglas del protocolo.


        Cuerpo del pedido: `{"name": "…", "chain": "ethereum", "contracts":
        [{"address": "0x…", "name": "…"}], "rules": {…},

        "shared": false, "events": [...]}`.


        - `contracts`: de 1 a 50. Cuentan contra el límite de vigilancias del
        plan. Se registran todos o ninguno.

        - `chain`: solo las redes listadas en `watchtower.chains` de `GET
        /v1/guard/status`.

        - `rules`: se combinan con las reglas por defecto (`presets.protocol` en
        `GET /v1/guard/status`):
         - `large_withdrawal`: lo que sale del contrato en una transacción, neto de lo que entra en la misma
         transacción, en USD y solo con activos con precio. Umbral `min_usd`, por defecto US$1,000,000. Un préstamo
         flash que se devuelve o un swap en un pool no lo alcanzan.
         - `authority_change`: cambio de propietario (owner) o de administrador (admin), y otorgar, quitar o cambiar el
         rol de administración. Con `all_roles: 1`, cualquier rol.
         - `authority_transfer_started`: la propuesta de un propietario o un administrador nuevo en un traspaso en dos
         pasos de OpenZeppelin, antes de que se acepte.
         - `proxy_upgrade`: upgrade del proxy o del beacon.
         - `pause`: pausa y reanudación.
         - `scheduled_change`: una llamada programada en un timelock o una propuesta de un governor registrados como
         contratos del protocolo. Avisa antes de la ejecución, con el efecto de la llamada simulado sobre el estado
         del bloque en que se programó. Ese estado puede cambiar antes de la ejecución, y un revert en la simulación
         no significa que la ejecución vaya a fallar.
         - `protocol_event`: los eventos propios declarados en `events`.
        - `events`: opcional, eventos propios a vigilar. Cada uno es
         `{"signature": "Evento(address indexed a, bool b)", "label": "…", "severity": "high", "contracts": ["0x…"]}`.
         `severity` es `high` por defecto, y `contracts` vacío aplica a todos los contratos del protocolo. Para elegirlo
         del ABI verificado, agregue `"source": "abi", "abi_address": "0x…"` (ver
         `GET /v1/guard/protocols/{pid}/abi-events`). Hasta 30 eventos, firmas de hasta 300 caracteres y hasta 3
         parámetros indexados. No se aceptan eventos anónimos, repetidos, de contratos ajenos al protocolo ni los que
         Guard ya lee (los de autoridad, `Transfer`, `Approval`, `ApprovalForAll`, `TransferSingle`, `TransferBatch`,
         `CallScheduled`, `QueueTransaction` y `ProposalCreated`).

        Las alertas de autoridad y las de cambios programados de severidad alta
        o crítica no se pierden por el tope diario

        de alertas. Las de eventos propios tienen un tope propio de 50 por
        contrato y por día. De un contrato se guardan

        sus eventos de autoridad y los de las transacciones con alerta, no cada
        transferencia.


        Responde el protocolo creado, con la misma forma que `GET
        /v1/guard/protocols/{pid}`.


        Errores:

        - `400`: red no disponible para Watchtower, nombre vacío, cantidad de
        contratos fuera de 1 a 50, dirección
         inválida o repetida, regla inválida, `shared` sin organización, o un evento inválido (incluido un contrato sin
         código verificado o una firma que no está en su ABI).
        - `403`: los contratos superan el límite de vigilancias del plan, o la
        clave de API no está asignada a una
         persona.
        - `404`: Watchtower no está habilitado.

        - `409`: uno de los contratos ya está vigilado.

        - `422`: el cuerpo del pedido trae un campo desconocido.

        - `502`: no se pudo leer el ABI verificado que necesita un evento;
        `detail.failure` describe la falla.


        **Costo:** sin cargo.
      operationId: create_protocol_v1_guard_protocols_post
      parameters:
        - 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.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProtocolCreate'
      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'
      security:
        - APIKeyHeader: []
        - BearerAuth: []
components:
  schemas:
    ProtocolCreate:
      properties:
        name:
          type: string
          title: Name
        chain:
          type: string
          title: Chain
          default: ethereum
        contracts:
          items:
            $ref: '#/components/schemas/ProtocolContract'
          type: array
          title: Contracts
        rules:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Rules
        shared:
          type: boolean
          title: Shared
          default: false
        events:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Events
      additionalProperties: false
      type: object
      required:
        - name
        - contracts
      title: ProtocolCreate
    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
    ProtocolContract:
      properties:
        address:
          type: string
          title: Address
        name:
          type: string
          title: Name
          default: ''
      additionalProperties: false
      type: object
      required:
        - address
      title: ProtocolContract
    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.