Skip to main content
POST
/
projects
/
{projectId}
/
investigations
Create investigation
curl --request POST \
  --url https://api.wavynode.com/v1/projects/{projectId}/investigations \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "<string>",
  "wallet": "<string>",
  "chainId": "<string>",
  "incremental": false
}
'
{
  "success": true,
  "data": {
    "id": "<string>",
    "project_id": 123,
    "analysis_id": "<string>",
    "analysis_status": "pending",
    "name": "<string>",
    "wallet": "<string>",
    "created_by": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "status": "active",
    "nodes": [
      {
        "id": "<string>",
        "type": "<string>",
        "data": {
          "address": "<string>",
          "label": "<string>",
          "balance": 123
        },
        "position": {
          "x": 123,
          "y": 123
        }
      }
    ],
    "edges": [
      {
        "id": "<string>",
        "source": "<string>",
        "target": "<string>",
        "data": {
          "amount": 123,
          "label": "<string>"
        }
      }
    ],
    "tracked_transactions": [
      {
        "protocol": "<string>",
        "amount": 123,
        "type": "in"
      }
    ]
  }
}

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.

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. 
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"
  }'

​
Request body

FieldTypeRequiredDescription
namestringyesHuman-readable name for the investigation
walletstringyesBlockchain address to investigate
chainIdstringnoChain ID (defaults to "1" — Ethereum mainnet)
incrementalbooleannoWhen true, runs a layer-by-layer incremental analysis. Default false

​
Response

{
  "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"
  }
}
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.

​
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 and Get layer result for details.

Analysis progress

Poll the current layer progress and provisional risk score.

Layer results

Fetch the cumulative graph and patterns for a specific depth layer.

Authorizations

​
x-api-key
string
header
required

Enter the full value with the ApiKey prefix. Example: ApiKey wavy_your-api-key. The prefix is required for authentication.

Path Parameters

​
projectId
string
required

The project ID

Body

application/json
​
name
string
required

Investigation name

​
wallet
string
required

Wallet address to investigate

​
chainId
string

Chain ID (defaults to '1' if not provided)

​
incremental
boolean
default:false

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.

Response

Investigation created

​
success
boolean
​
data
object