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

# Request a smart contract review

> Registers a smart contract review request for your organization.

**Request body (JSON).**
- `repo` (required): public GitHub repository, `https://github.com/<owner>/<repo>`. Private repositories and
 compressed files are not accepted yet.
- `commit` (required): full commit hash (40 hex). The whole report refers to that commit.
- `level`: `automated` (default), `assisted` or `audit`. The `audit` level requires `spec`.
- `files`: paths or patterns relative to the repository; a leading `!` excludes. Up to 50. Default:
 `src/**/*.sol` without tests, scripts or `lib/`.
- `spec`: specification or design document, up to 50,000 characters. Optional, except at the `audit` level.
- `project`: name for the dashboard; default, the repository name.

**Response.** `201` with `{demo, note, audit_id, audit, queue}`. `audit` has the shape of a row of
`GET /v1/audit`, with `run.state: "queued"` and `requested: true`. It is a real review of your organization
(`demo: false`), visible only to it.

**Availability.** Audit execution will be available soon. Until then, the review is registered in the queue but
does not run: `queue.state` is `not_enqueued` and `note` says so. Once execution is available, `queue.state`
will be `enqueued`. The sections of the review are empty, except `deploy` and `notas`: they are not filled with
example data, which would be invented findings about your code. An empty section does not mean “no findings”.

**Errors.** With body `{"error": …, "detail": …}`:
- `400`: `bad_repo`, `bad_commit`, `bad_level`, `bad_files`, `spec_required` or `spec_too_long`.
- `403 org_required`: an API key without an organization cannot request reviews. `403 read_only`: the role is
 read-only.
- `409 too_many_queued`: the organization already has 50 queued reviews that have not run.
- `503 queue_unavailable`: the review could not be queued; nothing is registered.

**Cost:** free.



## OpenAPI

````yaml /openapi.en.json post /v1/audit
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:
    post:
      tags:
        - Audit
      summary: Request a smart contract review
      description: >-
        Registers a smart contract review request for your organization.


        **Request body (JSON).**

        - `repo` (required): public GitHub repository,
        `https://github.com/<owner>/<repo>`. Private repositories and
         compressed files are not accepted yet.
        - `commit` (required): full commit hash (40 hex). The whole report
        refers to that commit.

        - `level`: `automated` (default), `assisted` or `audit`. The `audit`
        level requires `spec`.

        - `files`: paths or patterns relative to the repository; a leading `!`
        excludes. Up to 50. Default:
         `src/**/*.sol` without tests, scripts or `lib/`.
        - `spec`: specification or design document, up to 50,000 characters.
        Optional, except at the `audit` level.

        - `project`: name for the dashboard; default, the repository name.


        **Response.** `201` with `{demo, note, audit_id, audit, queue}`. `audit`
        has the shape of a row of

        `GET /v1/audit`, with `run.state: "queued"` and `requested: true`. It is
        a real review of your organization

        (`demo: false`), visible only to it.


        **Availability.** Audit execution will be available soon. Until then,
        the review is registered in the queue but

        does not run: `queue.state` is `not_enqueued` and `note` says so. Once
        execution is available, `queue.state`

        will be `enqueued`. The sections of the review are empty, except
        `deploy` and `notas`: they are not filled with

        example data, which would be invented findings about your code. An empty
        section does not mean “no findings”.


        **Errors.** With body `{"error": …, "detail": …}`:

        - `400`: `bad_repo`, `bad_commit`, `bad_level`, `bad_files`,
        `spec_required` or `spec_too_long`.

        - `403 org_required`: an API key without an organization cannot request
        reviews. `403 read_only`: the role is
         read-only.
        - `409 too_many_queued`: the organization already has 50 queued reviews
        that have not run.

        - `503 queue_unavailable`: the review could not be queued; nothing is
        registered.


        **Cost:** free.
      operationId: create_audit_v1_audit_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/AuditCreate'
      responses:
        '201':
          description: Review registered.
          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:
    AuditCreate:
      properties:
        repo:
          type: string
          title: Repo
          description: >-
            Repo público de GitHub: `https://github.com/<dueño>/<repo>`. Subir
            un zip todavía no se acepta.
        commit:
          type: string
          title: Commit
          description: >-
            Hash completo del commit (40 hex). Todo el informe refiere a ese
            hash.
        level:
          anyOf:
            - type: string
            - type: 'null'
          title: Level
          description: >-
            Nivel (D03): `automated` (Revisión automática), `assisted` (Revisión
            asistida) o `audit` (Auditoría, con un humano; pide `spec`).
          default: automated
        files:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Files
          description: >-
            Archivos en alcance: caminos o patrones relativos al repo; con `!`
            adelante excluye. Default: `src/**/*.sol` sin tests, scripts ni
            `lib/`.
        spec:
          anyOf:
            - type: string
            - type: 'null'
          title: Spec
          description: >-
            Especificación o README de diseño (opcional; obligatoria en
            `audit`), hasta 50,000 caracteres.
        project:
          anyOf:
            - type: string
            - type: 'null'
          title: Project
          description: 'Nombre del proyecto para el dashboard. Default: el nombre del repo.'
      type: object
      required:
        - repo
        - commit
      title: AuditCreate
    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.