> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wavynode.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create investigation

> Creates a new investigation for a wallet address. Optionally triggers an incremental layer-by-layer analysis.

Creates an investigation record and, if no prior analysis exists for the wallet, triggers a background risk analysis via the tracker service.

## Standard vs incremental analysis

By default, the analysis runs in **standard mode**: the API polls the tracker until the full result is ready, then stores it. The response includes the complete transaction graph.

When you pass `"incremental": true`, the tracker performs a **layer-by-layer BFS analysis**. Each depth layer is persisted independently so you can poll for partial results while the analysis is still running.

<Tabs>
  <Tab title="Standard">
    ```bash theme={null}
    curl -X POST https://api.wavynode.com/v1/projects/{projectId}/investigations \
      -H "x-api-key: ApiKey wavy_..." \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Binance Hot Wallet",
        "wallet": "0x28C6c06298d514Db089934071355E5743bf21d60",
        "chainId": "1"
      }'
    ```
  </Tab>

  <Tab title="Incremental (layer-by-layer)">
    ```bash theme={null}
    curl -X POST https://api.wavynode.com/v1/projects/{projectId}/investigations \
      -H "x-api-key: ApiKey wavy_..." \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Binance Hot Wallet",
        "wallet": "0x28C6c06298d514Db089934071355E5743bf21d60",
        "chainId": "1",
        "incremental": true
      }'
    ```
  </Tab>
</Tabs>

## Request body

| Field         | Type    | Required | Description                                                              |
| ------------- | ------- | -------- | ------------------------------------------------------------------------ |
| `name`        | string  | yes      | Human-readable name for the investigation                                |
| `wallet`      | string  | yes      | Blockchain address to investigate                                        |
| `chainId`     | string  | no       | Chain ID (defaults to `"1"` — Ethereum mainnet)                          |
| `incremental` | boolean | no       | When `true`, runs a layer-by-layer incremental analysis. Default `false` |

## Response

```json theme={null}
{
  "success": true,
  "data": {
    "id": "7d457074-055a-477e-a1a3-ae2ac446ba1b",
    "project_id": 1,
    "analysis_id": "eff04343-ce57-48c7-b478-f58531b1611f",
    "analysis_status": "pending",
    "name": "Binance Hot Wallet",
    "wallet": "0x28C6c06298d514Db089934071355E5743bf21d60",
    "status": "active",
    "nodes": [
      {
        "id": "0x28c6c06298d514db089934071355e5743bf21d60",
        "type": "wallet",
        "data": { "address": "0x28C6...", "label": "Root", "balance": 0 },
        "position": { "x": 0, "y": 0 }
      }
    ],
    "edges": [],
    "tracked_transactions": [],
    "created_at": "2026-04-29T16:17:14.000Z",
    "updated_at": "2026-04-29T16:17:14.000Z"
  }
}
```

<Note>
  The `analysis_id` may be empty initially if the analysis record is still being created in the background. Poll the investigation endpoint to get the updated `analysis_id`.
</Note>

## Polling for incremental results

When `incremental: true`, use these endpoints to track progress and fetch layer results as they complete:

1. **Poll progress** — `GET /v1/analysis/{analysisId}/progress`
2. **Fetch layer** — `GET /v1/analysis/{analysisId}/layers/{layer}`

See [Get analysis progress](/api-reference/endpoint/get-analysis-progress) and [Get layer result](/api-reference/endpoint/get-analysis-layer) for details.

<CardGroup cols={2}>
  <Card title="Analysis progress" icon="bars-progress" href="/api-reference/endpoint/get-analysis-progress">
    Poll the current layer progress and provisional risk score.
  </Card>

  <Card title="Layer results" icon="layer-group" href="/api-reference/endpoint/get-analysis-layer">
    Fetch the cumulative graph and patterns for a specific depth layer.
  </Card>
</CardGroup>


## OpenAPI

````yaml POST /projects/{projectId}/investigations
openapi: 3.1.0
info:
  title: Wavy Node API
  description: >-
    Compliance, fraud prevention, and risk analysis API for payment providers
    and cryptocurrency exchanges in Latin America.
  version: 1.0.0
  contact:
    name: Wavy Node Support
    email: support@wavynode.com
servers:
  - url: https://api.wavynode.com/v1
    description: Production
security:
  - apiKeyAuth: []
paths:
  /projects/{projectId}/investigations:
    post:
      tags:
        - Investigations
      summary: Create investigation
      description: >-
        Creates a new investigation for a wallet address. Optionally triggers an
        incremental layer-by-layer analysis.
      operationId: createInvestigation
      parameters:
        - name: projectId
          in: path
          required: true
          description: The project ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInvestigationRequest'
      responses:
        '200':
          description: Investigation created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/Investigation'
        '400':
          description: Invalid request body
        '401':
          description: Unauthorized
components:
  schemas:
    CreateInvestigationRequest:
      type: object
      required:
        - name
        - wallet
      properties:
        name:
          type: string
          description: Investigation name
        wallet:
          type: string
          description: Wallet address to investigate
        chainId:
          type: string
          description: Chain ID (defaults to '1' if not provided)
        incremental:
          type: boolean
          default: false
          description: >-
            When true, runs a layer-by-layer incremental analysis. Each BFS
            depth layer is persisted independently so you can poll for partial
            results while the analysis is still running.
    Investigation:
      type: object
      properties:
        id:
          type: string
          description: Investigation ID
        project_id:
          type: integer
        analysis_id:
          type: string
          nullable: true
          description: Linked analysis UUID
        analysis_status:
          type: string
          enum:
            - pending
            - running
            - completed
            - failed
          description: Status of the linked analysis
        name:
          type: string
        wallet:
          type: string
        created_by:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        status:
          type: string
          enum:
            - active
            - archived
        nodes:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              type:
                type: string
              data:
                type: object
                properties:
                  address:
                    type: string
                  label:
                    type: string
                  balance:
                    type: number
              position:
                type: object
                properties:
                  x:
                    type: number
                  'y':
                    type: number
          description: Transaction graph nodes
        edges:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              source:
                type: string
              target:
                type: string
              data:
                type: object
                properties:
                  amount:
                    type: number
                  label:
                    type: string
          description: Transaction graph edges
        tracked_transactions:
          type: array
          items:
            type: object
            properties:
              protocol:
                type: string
              amount:
                type: number
              type:
                type: string
                enum:
                  - in
                  - out
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Enter the full value with the `ApiKey` prefix. Example: `ApiKey
        wavy_your-api-key`. The prefix is required for authentication.

````