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

# Contribute a private label

> Saves a private label for an EVM address. Without `X-Case-Id`, the label belongs to your API key (or to your
user, from the app); with `X-Case-Id`, to the case. Only requests with that scope see it, never other
customers.

**Request body.** A `Label` object with `address` (`0x` + 40 hex), `chain`, `label`, `category`, `source` and
`confidence`. So that a contributed label cannot pose as another source, the server sets or limits these
fields:
- `added_by` and `method` are always saved as `"user"` and `"heuristic"`.
- `source` is saved as `"usuario: <text>"`, on one line and with up to 200 characters.
- `confidence`: a number between 0 and 1 (default 0.5), saved with a maximum of 0.5, below any other source.
- `category`: `bridge`, `contract`, `darknet`, `exchange`, `mixer`, `scam`, `unknown` or `victim`.
 `sanctioned` and `ex_sanctioned` are reserved: a sanction comes only from the official lists.
- `service_type`, `conflicting_tags` and `sanctions_history` are saved empty.

**Response.** `{"ok": true, "address": …, "label": {…}, "scope": {…}}`, with the label as saved and the scope
it was saved with.

**Errors.** `400` if the address is not EVM, if the category is reserved or invalid, if `confidence` is out of
range, or if `X-Case-Id` does not match a case you can edit (the label is not saved). `422` if a field does not
have the expected shape.

**Cost:** 1 credit.



## OpenAPI

````yaml /openapi.en.json post /v1/labels
openapi: 3.1.0
info:
  title: blockgence API
  description: >-
    The **blockgence** API provides fund tracing, entity attribution and
    explainable risk screening across several

    networks, with the evidence behind every result.


    ### Authentication

    Every `/v1/*` route requires an **API key**, sent in the `X-API-Key: <key>`
    header or as

    `Authorization: Bearer <key>`. Your organization issues the key. The
    evidence verification routes

    (`/v1/evidence/*`) do not require a key.


    ### Credits and limits

    Each plan has a **per-minute request limit** and a **monthly credit
    allowance**. Each operation states its cost in

    credits. **Only successful responses (status below 400) are charged:** an
    error response is recorded with 0

    credits. Check your usage with `GET /v1/account`.


    ### Data that could not be read

    If the data source cannot read what you requested, the response is `503
    source_unavailable`, with no charge,

    stating the source, the network, the query, the reason and whether a retry
    is advisable. If an intermediate step

    fails, the response is 200 and declares it in `degraded_sources` and in the
    `coverage_gaps` of the node or edge:

    in those cases, missing data does not mean missing activity.


    ### Networks

    `ethereum`, `bsc`, `polygon`, `arbitrum`, `base` and `optimism`; plus `tron`
    for tracing, profile, funding, network

    probing and transactions. `GET /v1/chains` states what can be queried on
    each network, at no cost. The networks

    `monero`, `bitcoin`, `litecoin` and `solana` are recognized in `/screening`
    and `/address`, where the network is

    inferred from the address format. Any other network returns `400`: it is
    never replaced with Ethereum.
  contact:
    name: blockgence
    url: https://www.blockgence.com/
  version: 1.0.0
servers:
  - url: https://app.blockgence.com
    description: Production
security: []
tags:
  - name: Platform
    description: >-
      Available networks, what can be queried on each one, from which sources
      and under which methodology. No cost.
  - name: Tracing
    description: >-
      Fund-flow tracing and reads of an address or a transaction: a
      time-consistent graph in both directions, funding, counterparties,
      bridges, swaps, mixers, labels and on-chain data.
  - name: Screening
    description: >-
      Risk screening of an address, with a recommendation (allow, review or
      block), its reasons and its sources.
  - name: Contracts
    description: Contract inspection and simulation of a transaction before signing it.
  - name: Tokens
    description: Token profile, with its issuer, supply, holders and risk signals.
  - name: Compromise
    description: >-
      Compromise vector of a stolen wallet, that is, how control of the funds
      was lost.
  - name: Incidents
    description: >-
      Incident response for victims, hacks and scams: playbook, freeze requests
      to issuers, post-mortem and deliverables.
  - name: Copilot
    description: >-
      AI investigation copilot that answers in natural language and cites the
      evidence (SSE streaming).
  - name: Cases
    description: >-
      Investigation cases to save, share and export, with their evidence,
      activity and annotations.
  - name: Permissions
    description: >-
      Approvals, delegations and signatures that grant access to an address's
      funds (ERC-20, Permit2 and EIP-7702).
  - name: Guard
    description: Wallet and protocol monitoring, with alerts by webhook and email.
  - name: Travel Rule
    description: >-
      Travel Rule without third-party connections: ownership challenge,
      counterparty, reconciliation and validation of IVMS101 messages.
  - name: Audit
    description: >-
      Smart contract audits, with the status, findings and evidence of each
      audit.
  - name: Evidence
    description: >-
      Verification of sealed evidence, with the signing public key and
      timestamps. No API key or charge required.
  - name: Monero
    description: >-
      Public profile of a Monero transaction and verification of a payment
      proof. Monero does not publish senders or amounts, so it is not traced.
  - name: Account
    description: Usage and limits of your API key.
  - name: Icons
    description: Entity logos to render graphs in your own interface. No cost.
  - name: Service
    description: Service status.
paths:
  /v1/labels:
    post:
      tags:
        - Tracing
      summary: Contribute a private label
      description: >-
        Saves a private label for an EVM address. Without `X-Case-Id`, the label
        belongs to your API key (or to your

        user, from the app); with `X-Case-Id`, to the case. Only requests with
        that scope see it, never other

        customers.


        **Request body.** A `Label` object with `address` (`0x` + 40 hex),
        `chain`, `label`, `category`, `source` and

        `confidence`. So that a contributed label cannot pose as another source,
        the server sets or limits these

        fields:

        - `added_by` and `method` are always saved as `"user"` and
        `"heuristic"`.

        - `source` is saved as `"usuario: <text>"`, on one line and with up to
        200 characters.

        - `confidence`: a number between 0 and 1 (default 0.5), saved with a
        maximum of 0.5, below any other source.

        - `category`: `bridge`, `contract`, `darknet`, `exchange`, `mixer`,
        `scam`, `unknown` or `victim`.
         `sanctioned` and `ex_sanctioned` are reserved: a sanction comes only from the official lists.
        - `service_type`, `conflicting_tags` and `sanctions_history` are saved
        empty.


        **Response.** `{"ok": true, "address": …, "label": {…}, "scope": {…}}`,
        with the label as saved and the scope

        it was saved with.


        **Errors.** `400` if the address is not EVM, if the category is reserved
        or invalid, if `confidence` is out of

        range, or if `X-Case-Id` does not match a case you can edit (the label
        is not saved). `422` if a field does not

        have the expected shape.


        **Cost:** 1 credit.
      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: >-
            Optional case the label is added to: the token of a case you can
            edit. Without this header, the label belongs to your API key. A case
            that does not exist or that you cannot edit returns `400` and the
            label is not saved.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Label'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema: {}
        '401':
          description: The API key is missing, invalid or revoked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: The monthly credits are exhausted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: >-
            The request does not have the expected shape; `detail` states which
            field to correct.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: >-
            The per-minute request limit was exceeded. Retry after the number of
            seconds in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: >-
            `source_unavailable`: the data source could not read what was
            requested. No credits are charged. If an intermediate step fails,
            the response is 200 and declares it in `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: >-
        Common shape of errors: a readable `detail` and, in many cases, an
        `error` with a stable code to recognize it without parsing the text.
      properties:
        detail:
          type: string
          description: What happened, in one sentence.
        error:
          type: string
          description: Stable error code, when there is one.
      required:
        - detail
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SourceUnavailable:
      type: object
      title: SourceUnavailable
      description: >-
        The data source could not read what was requested. No credits are
        charged. Missing data does not mean the address is risk-free or has no
        activity.
      properties:
        error:
          type: string
          enum:
            - source_unavailable
        detail:
          type: string
          description: What failed, where, and whether a retry is advisable.
        source:
          type: string
          description: >-
            Source that could not respond, for example `etherscan` or
            `blockscout`.
        chain:
          type: string
        primitive:
          type: string
          description: blockgence read that did not complete.
        operation:
          type: string
          description: Specific query to the source.
        target:
          type: string
          description: What was queried (address or transaction), abbreviated.
        reason:
          type: string
          description: >-
            Stable reason, for example `rate_limited`, `timeout` or
            `upstream_error`.
        retryable:
          type: boolean
        http_status:
          type:
            - integer
            - 'null'
        retry_after:
          type:
            - integer
            - 'null'
          description: >-
            Seconds to wait before retrying; also sent in the `Retry-After`
            header.
        upstream_message:
          type:
            - string
            - 'null'
        source_fault:
          type: boolean
          description: >-
            Whether the failure came from the source or from a limit of the
            query itself.
        failure_cause:
          type: string
          description: Cause of the failure, in one sentence.
      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: Your API key in the `X-API-Key` header.
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        The same API key as `Authorization: Bearer <key>`, as an alternative to
        `X-API-Key`.

````

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