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

# Ask the copilot of an audit

> Answers natural-language questions about an audit (its map, threat model, findings, leads, invariants, proofs,
execution and reviews) and can register work requests. The response is an SSE stream (`text/event-stream`).

**Request body (JSON).**
- `message` (required): the question, 1 to 4000 characters.
- `history`: previous turns `{role: user|assistant, content}`; the last 12 are used.
- `context`: what the user has on screen, `{section, selection: {kind, id}}`. It is validated against the
 audit: anything that does not exist in it is ignored.

**Events, in this order.**
- `start` `{audit_id}`: start of the response.
- `token` `{text}`: model text.
- `tool` `{name, input}` and `tool_result` `{name, audit_id, ok, request?}`: each tool the copilot used.
 `request` appears when it registered a request.
- `notice` `{audit_id, notice, detail}`: system notice. `model_fallback` (the default model was used),
 `truncated` (the response was cut for length) or `empty` (the model returned no text).
- `error` `{audit_id, error, detail}`: failure during the response (`llm_error` or `audit_source_unavailable`).
- `done` `{audit_id}`: end of the response.

Neither `notice` nor `error` is model text.

**What it can assert.** What the copilot says is not a finding. It cites findings by id, with the severity and
validation grade they already have, and leads by id as “unproven lead”, without severity. Anything it observes
in the code that is not a finding is raised as a question. It is limited to this audit, with the same access
control as `GET /v1/audit/{audit_id}/{section}`, and does not have the investigation tools of
`POST /v1/copilot`.

**Requests.** `request_poc` (a proof of concept on a lead) and `request_review` (the review of a function in the
map) only register a pending request, which is listed in `GET /v1/audit/{audit_id}/requests`; they do not run
anything. At most 3 new requests are registered per message.

**Errors before the stream.** With body `{"error": …, "detail": …}`; none of them queries the model:
- `400 bad_id` or `400 audit_id_mismatch`, as in `GET /v1/audit/{audit_id}`.
- `403 ai_disabled`: the organization disabled AI. No charge.
- `403 read_only`: the role is read-only, and requests write.
- `404 not_found`: the audit does not exist or belongs to another organization.
- `422`: `message` is empty or longer than 4000 characters.
- `503 llm_not_configured`: the copilot is not available at this time. `503 audit_source_unavailable`: the
 audit data could not be read.

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



## OpenAPI

````yaml /openapi.en.json post /v1/audit/{audit_id}/copilot
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/audit/{audit_id}/copilot:
    post:
      tags:
        - Audit
      summary: Ask the copilot of an audit
      description: >-
        Answers natural-language questions about an audit (its map, threat
        model, findings, leads, invariants, proofs,

        execution and reviews) and can register work requests. The response is
        an SSE stream (`text/event-stream`).


        **Request body (JSON).**

        - `message` (required): the question, 1 to 4000 characters.

        - `history`: previous turns `{role: user|assistant, content}`; the last
        12 are used.

        - `context`: what the user has on screen, `{section, selection: {kind,
        id}}`. It is validated against the
         audit: anything that does not exist in it is ignored.

        **Events, in this order.**

        - `start` `{audit_id}`: start of the response.

        - `token` `{text}`: model text.

        - `tool` `{name, input}` and `tool_result` `{name, audit_id, ok,
        request?}`: each tool the copilot used.
         `request` appears when it registered a request.
        - `notice` `{audit_id, notice, detail}`: system notice. `model_fallback`
        (the default model was used),
         `truncated` (the response was cut for length) or `empty` (the model returned no text).
        - `error` `{audit_id, error, detail}`: failure during the response
        (`llm_error` or `audit_source_unavailable`).

        - `done` `{audit_id}`: end of the response.


        Neither `notice` nor `error` is model text.


        **What it can assert.** What the copilot says is not a finding. It cites
        findings by id, with the severity and

        validation grade they already have, and leads by id as “unproven lead”,
        without severity. Anything it observes

        in the code that is not a finding is raised as a question. It is limited
        to this audit, with the same access

        control as `GET /v1/audit/{audit_id}/{section}`, and does not have the
        investigation tools of

        `POST /v1/copilot`.


        **Requests.** `request_poc` (a proof of concept on a lead) and
        `request_review` (the review of a function in the

        map) only register a pending request, which is listed in `GET
        /v1/audit/{audit_id}/requests`; they do not run

        anything. At most 3 new requests are registered per message.


        **Errors before the stream.** With body `{"error": …, "detail": …}`;
        none of them queries the model:

        - `400 bad_id` or `400 audit_id_mismatch`, as in `GET
        /v1/audit/{audit_id}`.

        - `403 ai_disabled`: the organization disabled AI. No charge.

        - `403 read_only`: the role is read-only, and requests write.

        - `404 not_found`: the audit does not exist or belongs to another
        organization.

        - `422`: `message` is empty or longer than 4000 characters.

        - `503 llm_not_configured`: the copilot is not available at this time.
        `503 audit_source_unavailable`: the
         audit data could not be read.

        **Cost:** 40 credits base. Some operations charge less when they reuse a
        saved result; never more.
      operationId: copilot_v1_audit__audit_id__copilot_post
      parameters:
        - name: audit_id
          in: path
          required: true
          schema:
            type: string
            title: Audit Id
          description: >-
            Audit id: lowercase letters, digits, `_` and `-`, 1 to 64
            characters, as listed by `GET /v1/audit`.
        - name: X-Audit-Id
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Audit-Id
          description: >-
            Optional id of the audit the client expects to be reading. If it
            does not match the `audit_id` in the path, the response is `400
            audit_id_mismatch` and nothing is read.
        - 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/AuditCopilotRequest'
      responses:
        '200':
          description: >-
            SSE stream (`text/event-stream`) with the `start`, `token`, `tool`,
            `tool_result`, `notice`, `error` and `done` events.
          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'
      security:
        - APIKeyHeader: []
        - BearerAuth: []
components:
  schemas:
    AuditCopilotRequest:
      properties:
        message:
          type: string
          maxLength: 4000
          minLength: 1
          title: Message
          description: La pregunta del usuario.
        history:
          items:
            additionalProperties: true
            type: object
          type: array
          maxItems: 40
          title: History
          description: >-
            Turnos previos `{role: user|assistant, content}` de esta
            conversación (se usan los últimos 12).
        context:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Context
          description: >-
            La pantalla: `{section, selection: {kind: finding|lead|proof, id}}`.
            Se valida contra la auditoría: lo que no existe en ella se ignora.
      type: object
      required:
        - message
      title: AuditCopilotRequest
    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
    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.