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

# Todas las contrapartes de una address (paginado) — revelar las ocultas del fan-out

> Universo completo de contrapartes de una address, agregado y paginado. NO
está capado por fan-out (trae hasta el máximo del provider), así se revelan las
contrapartes que el rastreo dejó afuera. Respeta consistencia temporal (`since`)
y devuelve cada contraparte ya etiquetada (label/category) para el grafo. Si la fuente no
puede leer la address → 503 (nunca «0 contrapartes»).

Límites de la fuente (`transfer_limits`: Bitquery en bsc trae solo salidas y, en plan free,
solo lo reciente): con direction=in y una fuente que no lee entradas no hay nada que responder
→ 503 sin cobro (antes: 200 con total 0, cobrado); con out/both la respuesta sale y el límite
va en `degraded_sources`.

Lectura enfocada: con `direction=out` y consistencia temporal, una address que no entra
en el tope de filas se completa desde la llegada de los fondos (`focus_after`), con el mismo piso que el nodo del
/trace (`engine._focus`: `since` o, si es posterior, `win_start`). Hasta acá se leía desde la punta: en una
address con mucha actividad posterior faltaban justo las salidas que siguen a la llegada, que el nodo sí había
leído, y el «+N» (`hidden_out`) no cuadraba con lo revelado. Lo que queda sin leer antes de la llegada va en
`transfers.truncated_outside`, como en el /trace.

La lectura del nodo, entera: `since`, `until`, `include_tokens` y `read_more`
son los que el nodo publica en `reveal`, y la lectura es la de su nodo en las TRES direcciones: con `in` o `both`,
`since` también enfoca la lectura (no filtra las entradas), y un padre (`until`) se completa hacia atrás desde su
última salida, como lo leyó el /trace. Así los cortes que trae revelar son los de la lectura del nodo y
la UI los puede sumar a su cobertura sin más: hasta esa versión, revelar las entradas de un nodo hacia adelante leía
desde la punta y le sumaba el corte entero de esa lectura como un tramo sin leer DENTRO del rastro, elegible para
«leer más», que relee hacia adelante. Los límites de las dos direcciones van una vez cada uno: los que viajan
con la lectura valen para las dos y `both` los declaraba dos veces.

Notables: la lectura pasa el `is_terminal` del rastreo como `keep`, con el alcance de
labels de quien pide, así una contraparte notable chica sobrevive al filtro de polvo como en el /trace.

**Costo:** 4 créditos de base (solo si la respuesta es < 400; algunas rutas cobran menos si reusan un resultado guardado).



## OpenAPI

````yaml /openapi.json post /v1/counterparties
openapi: 3.1.0
info:
  title: blockgence API
  description: >

    **blockgence** expone como API todo el motor de *blockchain intelligence*:

    rastreo de fondos (tracing), atribución de entidades y screening de riesgo

    explicable (glass-box), sobre múltiples chains EVM.


    ### Autenticación

    Todas las rutas `/v1/*` requieren una **API key**. Mandala en el header

    `X-API-Key: <key>` (o `Authorization: Bearer <key>`). La key te la entrega
    tu

    organización o el administrador. En esta página: **Authorize** → pegá la
    key, y cada

    «Try it out» → «Execute» es una request real, que se cobra igual que desde
    tu código.

    Las rutas de verificación de evidencia (`/v1/evidence/*`) son abiertas.


    ### Límites

    Cada tier tiene un **rate-limit por minuto** y una **cuota mensual de
    créditos**.

    Cada endpoint consume créditos según su costo (`/trace` es el más caro); el
    costo puede

    variar por método y sub-ruta. **Solo se cobran las respuestas exitosas
    (status < 400)**:

    una request que termina en error queda registrada con 0 créditos. Consultá
    tu consumo en

    tiempo real con `GET /v1/account`.


    ### Fallas de la fuente de datos

    Si la fuente de datos falla al leer lo que pediste, la respuesta es `503
    source_unavailable`

    (sin cobro), con la fuente, la chain, la consulta, el motivo y si conviene
    reintentar. Si

    falla un salto intermedio, la respuesta es 200 y lo declara en
    `degraded_sources` (y en el

    `coverage_gaps` del nodo o la arista): ahí, la ausencia de datos no es
    ausencia de movimientos.


    ### Chains soportadas

    `ethereum`, `bsc`, `polygon`, `arbitrum`, `base`, `optimism`; además `tron`
    (rastreo, ficha, fondeo, probe y tx: ver «Tron» en `docs/API.md`). Qué
    fuente sirve cada consulta y con qué límite está en `GET /v1/chains` (0
    créditos). Conocidas y no consultadas (valen en `/screening` y `/address`,
    donde la chain la define el formato de la address): `monero`, `bitcoin`,
    `litecoin`, `solana`.

    Cualquier otra chain es `400`: nunca se sustituye 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: Platform
    description: >-
      Qué chains hay y qué puede servir cada una (registro y matriz de
      capacidades), con qué fuentes y con qué metodología. Costo: 0 créditos.
  - name: Tracking
    description: >-
      Rastreo del flujo de fondos y lecturas de una address o una tx: grafo
      bidireccional con consistencia temporal, fondeo, contrapartes, bridges,
      swaps, mixers, labels y datos on-chain.
  - name: Screening
    description: >-
      Screening de riesgo: ¿esta address es riesgosa? Recomendación
      allow/review/block, con las razones y su fuente.
  - name: Contracts
    description: Inspector de contratos y simulación de transacciones antes de firmar.
  - name: Tokens
    description: 'Ficha de un token: emisor, supply, holders y señales de riesgo.'
  - name: Compromise
    description: 'Vector de compromiso de una wallet robada: cómo se perdió el control.'
  - name: Incident
    description: >-
      Respuesta a incidentes: víctima, hack y estafa. Playbook, freeze de fondos
      en emisores, post-mortem y entregables.
  - name: Copilot
    description: >-
      Copiloto forense con IA: investigá en lenguaje natural, con narrativa
      citada (streaming SSE).
  - name: Cases
    description: >-
      Casos: guardar, compartir y exportar investigaciones, con su evidencia,
      actividad y anotaciones.
  - name: Permissions
    description: >-
      Approvals, delegaciones y firmas que dan acceso a los fondos de una
      address (ERC-20, Permit2, EIP-7702).
  - name: Guard
    description: >-
      Blockgence Guard: vigilancia activa de wallets y protocolos, con alertas
      por webhook y correo.
  - name: Travel Rule
    description: >-
      Travel Rule sin red: desafío de titularidad, contraparte, conciliación y
      validación de mensajes IVMS101.
  - name: Auditoría
    description: >-
      Auditoría de smart contracts: pedir una revisión, su estado y hallazgos,
      las addresses desplegadas y las notas del equipo.
  - name: Evidencia
    description: >-
      Verificación de la evidencia sellada: clave pública de firma y sellos de
      tiempo. Abiertas: no piden API key ni cobran.
  - name: Monero
    description: >-
      Ficha pública de una tx de Monero y prueba de pago XMR (tx key u
      OutProof/InProof), verificada localmente y sellada. Monero no publica
      remitentes ni montos: no se rastrea.
  - name: Account
    description: Tu consumo y límites (self-service).
  - name: Icons
    description: >-
      Logos de entidades para renderizar grafos en tu UI. Cache-first
      (TrustWallet, 1inch, favicons oficiales). Costo: 0 créditos.
  - name: Meta
    description: Health y estado operacional (sin auth).
paths:
  /v1/counterparties:
    post:
      tags:
        - Tracking
      summary: >-
        Todas las contrapartes de una address (paginado) — revelar las ocultas
        del fan-out
      description: >-
        Universo completo de contrapartes de una address, agregado y paginado.
        NO

        está capado por fan-out (trae hasta el máximo del provider), así se
        revelan las

        contrapartes que el rastreo dejó afuera. Respeta consistencia temporal
        (`since`)

        y devuelve cada contraparte ya etiquetada (label/category) para el
        grafo. Si la fuente no

        puede leer la address → 503 (nunca «0 contrapartes»).


        Límites de la fuente (`transfer_limits`: Bitquery en bsc trae solo
        salidas y, en plan free,

        solo lo reciente): con direction=in y una fuente que no lee entradas no
        hay nada que responder

        → 503 sin cobro (antes: 200 con total 0, cobrado); con out/both la
        respuesta sale y el límite

        va en `degraded_sources`.


        Lectura enfocada: con `direction=out` y consistencia temporal, una
        address que no entra

        en el tope de filas se completa desde la llegada de los fondos
        (`focus_after`), con el mismo piso que el nodo del

        /trace (`engine._focus`: `since` o, si es posterior, `win_start`). Hasta
        acá se leía desde la punta: en una

        address con mucha actividad posterior faltaban justo las salidas que
        siguen a la llegada, que el nodo sí había

        leído, y el «+N» (`hidden_out`) no cuadraba con lo revelado. Lo que
        queda sin leer antes de la llegada va en

        `transfers.truncated_outside`, como en el /trace.


        La lectura del nodo, entera: `since`, `until`, `include_tokens` y
        `read_more`

        son los que el nodo publica en `reveal`, y la lectura es la de su nodo
        en las TRES direcciones: con `in` o `both`,

        `since` también enfoca la lectura (no filtra las entradas), y un padre
        (`until`) se completa hacia atrás desde su

        última salida, como lo leyó el /trace. Así los cortes que trae revelar
        son los de la lectura del nodo y

        la UI los puede sumar a su cobertura sin más: hasta esa versión, revelar
        las entradas de un nodo hacia adelante leía

        desde la punta y le sumaba el corte entero de esa lectura como un tramo
        sin leer DENTRO del rastro, elegible para

        «leer más», que relee hacia adelante. Los límites de las dos direcciones
        van una vez cada uno: los que viajan

        con la lectura valen para las dos y `both` los declaraba dos veces.


        Notables: la lectura pasa el `is_terminal` del rastreo como `keep`, con
        el alcance de

        labels de quien pide, así una contraparte notable chica sobrevive al
        filtro de polvo como en el /trace.


        **Costo:** 4 créditos de base (solo si la respuesta es < 400; algunas
        rutas cobran menos si reusan un resultado guardado).
      operationId: counterparties_v1_counterparties_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 podés ver. La
            consulta queda en el registro de actividad de ese caso y resuelve
            también sus labels propias. Un caso que no existe, se borró o ya no
            está compartido con vos da `400 case_unavailable` y la consulta no
            se hace (sin cobro).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CounterpartiesRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '401':
          description: Falta la API key o es inválida o revocada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Cuota mensual de créditos agotada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: >-
            Rate limit por minuto superado. Reintentá después de `Retry-After`
            segundos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: >-
            `source_unavailable`: la fuente de datos (o el índice de labels) no
            pudo leer lo pedido. Sin cobro. Si falla un salto intermedio la
            respuesta es 200 y lo declara en `degraded_sources`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceUnavailable'
      security:
        - APIKeyHeader: []
        - BearerAuth: []
components:
  schemas:
    CounterpartiesRequest:
      properties:
        address:
          type: string
          title: Address
        chain:
          type: string
          title: Chain
          default: ethereum
        direction:
          type: string
          title: Direction
          default: both
        since:
          type: integer
          title: Since
          default: 0
        temporal:
          type: boolean
          title: Temporal
          default: true
        win_start:
          type: integer
          title: Win Start
          default: 0
        win_end:
          type: integer
          title: Win End
          default: 0
        min_usd:
          type: number
          title: Min Usd
          default: 1
        offset:
          type: integer
          title: Offset
          default: 0
        limit:
          type: integer
          title: Limit
          default: 20
        include_tokens:
          type: boolean
          title: Include Tokens
          default: true
        read_more:
          type: integer
          title: Read More
          default: 0
        until:
          type: integer
          title: Until
          default: 0
      type: object
      required:
        - address
      title: CounterpartiesRequest
      description: >-
        Todas las contrapartes de UNA address, agregadas y paginadas. A
        diferencia

        del trace (capado por fan-out), acá se ve el universo completo de
        contrapartes

        (hasta lo que trae el provider), para revelar las que el rastreo dejó
        afuera.
    Error:
      type: object
      title: Error
      description: >-
        Forma de todos los errores: un `detail` legible. Algunos agregan
        `error`, un código estable para reconocerlo sin leer el texto
        (`case_unavailable`, `case_read_only`, …).
      properties:
        detail:
          type: string
          description: Qué pasó, 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 dice que la address esté limpia ni sin 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 falló: `etherscan`, `blockscout`, `bitquery`, `goplus`,
            `osint`, `config`, …
        chain:
          type: string
        primitive:
          type: string
          description: Lectura de blockgence que falló.
        operation:
          type: string
          description: Llamada concreta a la fuente.
        target:
          type: string
          description: Lo consultado (address o tx), abreviado.
        reason:
          type: string
          description: >-
            Motivo estable: `rate_limited`, `quota_exhausted`, `not_in_plan`,
            `unauthorized`, `timeout`, `network`, `upstream_error`, … (tabla en
            docs/API.md).
        retryable:
          type: boolean
        http_status:
          type:
            - integer
            - 'null'
        retry_after:
          type:
            - integer
            - 'null'
          description: Segundos; viene también como header `Retry-After`.
        upstream_message:
          type:
            - string
            - 'null'
        source_fault:
          type: boolean
          description: >-
            Si fue una falla de la fuente o un tope de blockgence / una consulta
            que no se hizo.
        failure_cause:
          type: string
          description: Por qué, en una cláusula.
      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: Tu API key en el header `X-API-Key`.
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        La misma API key en `Authorization: Bearer <key>` (alternativa a
        `X-API-Key`).

````

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