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

import requests

url = "https://api.wavynode.com/v1/projects/{projectId}/investigations"

payload = {
    "name": "<string>",
    "wallet": "<string>",
    "chainId": "<string>",
    "incremental": False
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({name: '<string>', wallet: '<string>', chainId: '<string>', incremental: false})
};

fetch('https://api.wavynode.com/v1/projects/{projectId}/investigations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.wavynode.com/v1/projects/{projectId}/investigations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'wallet' => '<string>',
    'chainId' => '<string>',
    'incremental' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.wavynode.com/v1/projects/{projectId}/investigations"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"wallet\": \"<string>\",\n  \"chainId\": \"<string>\",\n  \"incremental\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.wavynode.com/v1/projects/{projectId}/investigations")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"wallet\": \"<string>\",\n  \"chainId\": \"<string>\",\n  \"incremental\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.wavynode.com/v1/projects/{projectId}/investigations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"wallet\": \"<string>\",\n  \"chainId\": \"<string>\",\n  \"incremental\": false\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "id": "<string>",
    "project_id": 123,
    "analysis_id": "<string>",
    "name": "<string>",
    "wallet": "<string>",
    "created_by": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "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
      }
    ]
  }
}

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

import requests

url = "https://api.wavynode.com/v1/projects/{projectId}/investigations"

payload = {
    "name": "<string>",
    "wallet": "<string>",
    "chainId": "<string>",
    "incremental": False
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({name: '<string>', wallet: '<string>', chainId: '<string>', incremental: false})
};

fetch('https://api.wavynode.com/v1/projects/{projectId}/investigations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.wavynode.com/v1/projects/{projectId}/investigations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'wallet' => '<string>',
    'chainId' => '<string>',
    'incremental' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.wavynode.com/v1/projects/{projectId}/investigations"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"wallet\": \"<string>\",\n  \"chainId\": \"<string>\",\n  \"incremental\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.wavynode.com/v1/projects/{projectId}/investigations")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"wallet\": \"<string>\",\n  \"chainId\": \"<string>\",\n  \"incremental\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.wavynode.com/v1/projects/{projectId}/investigations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"wallet\": \"<string>\",\n  \"chainId\": \"<string>\",\n  \"incremental\": false\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "id": "<string>",
    "project_id": 123,
    "analysis_id": "<string>",
    "name": "<string>",
    "wallet": "<string>",
    "created_by": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "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
      }
    ]
  }
}

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.

Standard
Incremental (layer-by-layer)

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

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

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

{
  "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:

Poll progress — GET /v1/analysis/{analysisId}/progress
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

Show child attributes

Scan risk List investigations

Introduction

Chains

Addresses

Status

Scan Risk

Investigations

Analysis

Reports

API Keys

Create investigation

Standard vs incremental analysis

Request body

Response

Polling for incremental results

Analysis progress

Layer results

Authorizations

Path Parameters

Body

Response

​Standard vs incremental analysis

​Request body

​Response

​Polling for incremental results

Analysis progress

Layer results

Authorizations

Path Parameters

Body

Response

Standard vs incremental analysis

Request body

Response

Polling for incremental results