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

# Start the incident playbook

> Creates an asynchronous job that analyzes an incident and builds the case in a single request. It responds 202
with the `job_id`; progress is available at `GET /v1/incident/{job_id}`.

Request body, with exactly one input among `exploit_tx`, `victim` and `addresses`:
- `chain`: EVM network (defaults to `ethereum`);
- `exploit_tx`: the exploit transaction;
- `victim`: the victim's address; the trace starts from it;
- `addresses`: up to 60 attacker addresses, with a mandatory `addresses_source` (where the list comes from). The
 attribution belongs to that source, not to blockgence;
- `hops` (from 1 to 5, defaults to 2) and `fanout` (from 1 to 10, defaults to 4): hops and branches per node of
 the trace. An out-of-range value is adjusted to the nearest limit;
- `since`: from when to follow the funds (unix), with `victim` or `addresses`;
- `window_days`: days of the trace window from the exploit date or from `since`. With `exploit_tx`, 30 by default
 and up to 180; `0` means no limit. With `victim` or `addresses` it requires `since`;
- `max_credits`: cap on the credits of the steps, excluding orchestration (defaults to 200, up to 5,000);
- `name`: name of the case;
- `watch`: `{create, follow_hops, shared}`, to create a Guard watch for each attacker account. Without `watch`,
 the watches are only offered;
- `protocol_addresses`: up to 20 protocol addresses, `{address, role, source}`, to recognize returns.

The steps, in order, are `decode`, `attacker`, `stolen`, `trace` (in batches of up to 5 seeds), `freeze`,
`case`, `postmortem` and `watchlist`. Each one ends as `ok`, `skipped` or `error`, with its reason, its evidence
and the credits it cost (`credits`).

Orchestration is charged when the job is created, and each step that completes successfully is charged
separately. A step that fails is not charged. If the month's credits or `max_credits` are not enough for a step,
that step is `skipped` and the job continues without it.

The same request from the same API key within 24 hours returns that job (200, `idempotent_replay: true`) at no
charge, unless it ended in `error`, was interrupted or its case was deleted. Up to 2 jobs in progress are allowed
per API key; beyond that, the response is 429 at no charge. An invalid request returns 400 at no charge.

**Cost:** 40 credits when the job is created, plus each step that completes successfully, up to the request's `max_credits` cap. A failed step is not charged. Repeating the same request returns the existing job, with no charge.



## OpenAPI

````yaml /openapi.en.json post /v1/incident
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/incident:
    post:
      tags:
        - Incidents
      summary: Start the incident playbook
      description: >-
        Creates an asynchronous job that analyzes an incident and builds the
        case in a single request. It responds 202

        with the `job_id`; progress is available at `GET /v1/incident/{job_id}`.


        Request body, with exactly one input among `exploit_tx`, `victim` and
        `addresses`:

        - `chain`: EVM network (defaults to `ethereum`);

        - `exploit_tx`: the exploit transaction;

        - `victim`: the victim's address; the trace starts from it;

        - `addresses`: up to 60 attacker addresses, with a mandatory
        `addresses_source` (where the list comes from). The
         attribution belongs to that source, not to blockgence;
        - `hops` (from 1 to 5, defaults to 2) and `fanout` (from 1 to 10,
        defaults to 4): hops and branches per node of
         the trace. An out-of-range value is adjusted to the nearest limit;
        - `since`: from when to follow the funds (unix), with `victim` or
        `addresses`;

        - `window_days`: days of the trace window from the exploit date or from
        `since`. With `exploit_tx`, 30 by default
         and up to 180; `0` means no limit. With `victim` or `addresses` it requires `since`;
        - `max_credits`: cap on the credits of the steps, excluding
        orchestration (defaults to 200, up to 5,000);

        - `name`: name of the case;

        - `watch`: `{create, follow_hops, shared}`, to create a Guard watch for
        each attacker account. Without `watch`,
         the watches are only offered;
        - `protocol_addresses`: up to 20 protocol addresses, `{address, role,
        source}`, to recognize returns.


        The steps, in order, are `decode`, `attacker`, `stolen`, `trace` (in
        batches of up to 5 seeds), `freeze`,

        `case`, `postmortem` and `watchlist`. Each one ends as `ok`, `skipped`
        or `error`, with its reason, its evidence

        and the credits it cost (`credits`).


        Orchestration is charged when the job is created, and each step that
        completes successfully is charged

        separately. A step that fails is not charged. If the month's credits or
        `max_credits` are not enough for a step,

        that step is `skipped` and the job continues without it.


        The same request from the same API key within 24 hours returns that job
        (200, `idempotent_replay: true`) at no

        charge, unless it ended in `error`, was interrupted or its case was
        deleted. Up to 2 jobs in progress are allowed

        per API key; beyond that, the response is 429 at no charge. An invalid
        request returns 400 at no charge.


        **Cost:** 40 credits when the job is created, plus each step that
        completes successfully, up to the request's `max_credits` cap. A failed
        step is not charged. Repeating the same request returns the existing
        job, with no charge.
      operationId: incident_start_v1_incident_post
      parameters:
        - 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.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IncidentRequest'
      responses:
        '202':
          description: >-
            Job created. The response includes the `job_id`, the initial status
            of each step and `idempotent_replay: false`.
          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:
    IncidentRequest:
      properties:
        chain:
          type: string
          title: Chain
          default: ethereum
        exploit_tx:
          anyOf:
            - type: string
            - type: 'null'
          title: Exploit Tx
        victim:
          anyOf:
            - type: string
            - type: 'null'
          title: Victim
        addresses:
          anyOf:
            - items:
                type: string
              type: array
              maxItems: 60
            - type: 'null'
          title: Addresses
        addresses_source:
          anyOf:
            - type: string
            - type: 'null'
          title: Addresses Source
        hops:
          type: integer
          title: Hops
          default: 2
        fanout:
          type: integer
          title: Fanout
          default: 4
        since:
          type: integer
          title: Since
          default: 0
        window_days:
          anyOf:
            - type: integer
            - type: 'null'
          title: Window Days
        max_credits:
          type: integer
          title: Max Credits
          default: 200
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        watch:
          anyOf:
            - $ref: '#/components/schemas/IncidentWatch'
            - type: 'null'
        protocol_addresses:
          anyOf:
            - items:
                $ref: >-
                  #/components/schemas/backend__modules__incident__playbook__ProtocolAddress
              type: array
              maxItems: 20
            - type: 'null'
          title: Protocol Addresses
      type: object
      title: IncidentRequest
    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
    IncidentWatch:
      properties:
        create:
          type: boolean
          title: Create
          default: true
        follow_hops:
          type: boolean
          title: Follow Hops
          default: true
        shared:
          type: boolean
          title: Shared
          default: false
      type: object
      title: IncidentWatch
      description: >-
        Qué hace el paso `watchlist` con las cuentas del atacante. Sin este
        objeto, las ofrece y no crea nada.
    backend__modules__incident__playbook__ProtocolAddress:
      properties:
        address:
          type: string
          title: Address
        role:
          type: string
          title: Role
          default: protocol
        source:
          type: string
          maxLength: 300
          minLength: 1
          title: Source
      type: object
      required:
        - address
        - source
      title: ProtocolAddress
      description: >-
        Una address del lado del protocolo para el clasificador de devoluciones,
        con su fuente: la de

        recuperación o una del protocolo (su deployer, su tesorería). Una
        devolución a ella cuenta como devuelta.
    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.