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

# Address screening

> Assesses the risk of an address in a single query (it is not continuous transaction monitoring) and returns a
recommendation: `allow`, `review` or `block`, with its reasons and its sources. It combines blockgence labels
(sanctions lists, community sources and the private labels visible to your API key or your case), live
attribution, the GoPlus malicious address flags and the freeze status set by stablecoin issuers.

Main fields:
- `recommendation` and `risk` (`score`, `level` and `reasons`, each reason with its source).
- `label`, `category` and `labels[]`, with the source, method and confidence of each label.
- `known`: `false` if no source identifies the address. An `allow` with `known: false` means the address does
 not appear in the sources, not that it has been reviewed and is free of risk.
- `sanctions_status`: `sanctioned` (an applied list includes it today), `delisted` (it was listed and removed:
 it neither blocks nor adds risk), `conflict` (it has a delisting, but the current list includes it again) or
 `null`. `sanctions_history` is the timeline of listings and delistings; in each event,
 `date_precision: entity` means the date is the listing date of the entity, not of the address.
- `sanctions_lists`: which lists it was assessed against (`applied`), the designations in lists your
 organization did not select (`not_applied`, cited, with no effect on the recommendation) and the lists that
 are not loaded (`not_loaded`).
- `issuer_freeze`: whether an issuer froze the address, read on-chain at a fixed block. An active freeze raises
 `allow` to `review`. `frozen: null` means it could not be determined, not that the address is not frozen.
- `malicious_flags`: the GoPlus flags. They raise `allow` to `review`, but never block on their own.
- `service_type` (for example `instant-exchanger` or `privacy-pool`, where the trail ends) and
 `conflicting_tags` (third-party flags cited but not applied). Neither changes the recommendation.
- `not_covered`: what the screening does not assess on that network, by design.
- `degraded_sources`: the sources that did not respond. With a failure, the recommendation is calculated with
 the others and an empty `malicious_flags` does not mean “no flags”.

Only an active sanction produces `block`.

Address formats: EVM, Tron, Monero (mainnet only), Bitcoin, Litecoin and Solana. On networks that are not EVM,
the network is inferred from the format, the address is sent without changing its case and only blockgence
labels count, including the sanctions lists. An EVM address with a network that does not match, or an
unrecognized format, returns `400`.

**Cost:** 3 credits base. Some operations charge less when they reuse a saved result; never more.



## OpenAPI

````yaml /openapi.en.json get /v1/screening/{addr}
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/screening/{addr}:
    get:
      tags:
        - Screening
      summary: Address screening
      description: >-
        Assesses the risk of an address in a single query (it is not continuous
        transaction monitoring) and returns a

        recommendation: `allow`, `review` or `block`, with its reasons and its
        sources. It combines blockgence labels

        (sanctions lists, community sources and the private labels visible to
        your API key or your case), live

        attribution, the GoPlus malicious address flags and the freeze status
        set by stablecoin issuers.


        Main fields:

        - `recommendation` and `risk` (`score`, `level` and `reasons`, each
        reason with its source).

        - `label`, `category` and `labels[]`, with the source, method and
        confidence of each label.

        - `known`: `false` if no source identifies the address. An `allow` with
        `known: false` means the address does
         not appear in the sources, not that it has been reviewed and is free of risk.
        - `sanctions_status`: `sanctioned` (an applied list includes it today),
        `delisted` (it was listed and removed:
         it neither blocks nor adds risk), `conflict` (it has a delisting, but the current list includes it again) or
         `null`. `sanctions_history` is the timeline of listings and delistings; in each event,
         `date_precision: entity` means the date is the listing date of the entity, not of the address.
        - `sanctions_lists`: which lists it was assessed against (`applied`),
        the designations in lists your
         organization did not select (`not_applied`, cited, with no effect on the recommendation) and the lists that
         are not loaded (`not_loaded`).
        - `issuer_freeze`: whether an issuer froze the address, read on-chain at
        a fixed block. An active freeze raises
         `allow` to `review`. `frozen: null` means it could not be determined, not that the address is not frozen.
        - `malicious_flags`: the GoPlus flags. They raise `allow` to `review`,
        but never block on their own.

        - `service_type` (for example `instant-exchanger` or `privacy-pool`,
        where the trail ends) and
         `conflicting_tags` (third-party flags cited but not applied). Neither changes the recommendation.
        - `not_covered`: what the screening does not assess on that network, by
        design.

        - `degraded_sources`: the sources that did not respond. With a failure,
        the recommendation is calculated with
         the others and an empty `malicious_flags` does not mean “no flags”.

        Only an active sanction produces `block`.


        Address formats: EVM, Tron, Monero (mainnet only), Bitcoin, Litecoin and
        Solana. On networks that are not EVM,

        the network is inferred from the format, the address is sent without
        changing its case and only blockgence

        labels count, including the sanctions lists. An EVM address with a
        network that does not match, or an

        unrecognized format, returns `400`.


        **Cost:** 3 credits base. Some operations charge less when they reuse a
        saved result; never more.
      operationId: screening_route_v1_screening__addr__get
      parameters:
        - name: addr
          in: path
          required: true
          schema:
            type: string
            title: Addr
          description: >-
            Address to assess: EVM (`0x` followed by 40 hexadecimal characters),
            Tron (`T…`), Monero, Bitcoin, Litecoin or Solana. Addresses that are
            not EVM are sent as they are, preserving case. Another format
            returns `400`.
        - name: chain
          in: query
          required: false
          schema:
            type: string
            title: Chain
            default: ethereum
          description: >-
            Network to query for an EVM address (see `GET /v1/chains`). Default:
            `ethereum`. For the other families, the network is inferred from the
            address format. A `3…` address, valid on both Bitcoin and Litecoin,
            is assessed on Litecoin only with `chain=litecoin`.
        - name: X-Case-Id
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Case-Id
          description: >-
            Active case, optional: the token of a case you can view. The query
            is recorded in that case and also uses its own labels. A case that
            does not exist, was deleted or is no longer shared with you returns
            `400 case_unavailable` and the query is not run, with no charge.
      responses:
        '200':
          description: The recommendation, the risk, the labels and the screening coverage.
          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:
    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
    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: 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.