Use case 2: Identifying Related Wallets at Scale

Scenario

An address clustering workflow that uses the Nansen API to systematically identify related wallet addresses and analyze their relationships. This enables researchers to uncover wallet connections through funding patterns, shared interactions, and behavioral analysis across multiple blockchains.

Core Components

• Labels: Find labels of the initial address

• Related Wallets: Detection of special connections (funding, signing, contract deployment)

• Counterparties Analysis: Identification of high-interaction addresses and shared patterns

This integration enables systematic discovery of wallet clusters through multiple relationship types and confidence levels.

Workflow Implementation

Step 1: Tarket Address Label Lookup

• Query labels of the target address

Step 2: Initial Relationship Discovery

• Query Related Wallets endpoint with target address

• Identify direct relationships: relation: "First Funder", "Signer", "Deployed via"

• Build initial cluster with high-confidence connections

Step 3: Counterparty Analysis

• Analyze counterparties with group_by: "entity" for entity-level grouping

• Filter for volume_in_usd > 50000 to find significant addresses

• Identify shared CEX deposit addresses across potential cluster members

Step 4: Pattern Recognition

• Compare transaction timing using block_timestamp fields

• Look for addresses with similar method: "0x" patterns

• Check for coordinated movements with matching transaction_type values

Step 5: Multi-Level Clustering

• For each high-confidence related address, repeat steps 1-3

• Cross-reference addresses that deposit to same CEX addresses

• Build network graph of relationships with confidence scores

Step 6: Confidence Assessment

• High confidence (>90%): First funder, shared signers, same CEX deposits

• Medium confidence (60-90%): High interaction volume, coordinated timing

• Low confidence (<60%): Indirect relationships, behavioral similarities

Step 7: Validation and Refinement

• Check balance patterns for coordinated movements

• Filter out false positives from common protocol interactions

Code Examples

1. Find Target Address Labels

Identify all the labels associated with the target address

curl -L \
  --request POST \
  --url 'https://api.nansen.ai/api/beta/profiler/address/labels' \
  --header 'apiKey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "parameters": {
      "chain": "ethereum",
      "address": "0xbdfa4f4492dd7b7cf211209c4791af8d52bf5c50"
    },
    "pagination": {
      "page": 1,
      "recordsPerPage": 100
    }
  }'

2. Find Related Wallets (Direct Relationships)

Identify wallets with special connections to a target address:

curl -X POST "https://api.nansen.ai/api/v1/profiler/address/related-wallets" \
  -H "apiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0x28c6c06298d514db089934071355e5743bf21d60",
    "chain": "ethereum",
    "pagination": {
      "page": 1,
      "per_page": 20
    }
  }'

This reveals first funder relationships, signer connections, multisig relationships, and contract deployment patterns.

3. Analyze Address Counterparties

Find addresses with the highest interaction volume:

curl -X POST "https://api.nansen.ai/api/v1/profiler/address/counterparties" \
  -H "apiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0x28c6c06298d514db089934071355e5743bf21d60",
    "chain": "ethereum",
    "date": {
      "from": "2024-07-01",
      "to": "2025-01-21"
    },
    "group_by": "wallet",
    "source_input": "Combined",
    "filters": {
      "total_volume_usd": {
        "min": 10000
      }
    },
    "order_by": [
      {
        "field": "total_volume_usd",
        "direction": "DESC"
      }
    ]
  }'

This identifies CEX deposit addresses and high-frequency interaction patterns crucial for clustering.

4. Track Historical Balance Patterns

Analyze coordinated balance movements across potential cluster members:

curl -X POST "https://api.nansen.ai/api/v1/profiler/address/historical-balances" \
  -H "apiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0x28c6c06298d514db089934071355e5743bf21d60",
    "chain": "ethereum",
    "date": {
      "from": "2024-10-01",
      "to": "2025-01-21"
    },
    "filters": {
      "token_symbol": "USDC",
      "value_usd": {
        "min": 1000
      }
    }
  }'

Coordinated balance changes across addresses indicate potential cluster membership.

5. Examine Transaction Patterns

Review transaction history for behavioral similarities:

curl -X POST "https://api.nansen.ai/api/v1/profiler/address/transactions" \
  -H "apiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0x28c6c06298d514db089934071355e5743bf21d60",
    "chain": "ethereum",
    "date": {
      "from": "2025-01-01",
      "to": "2025-01-21"
    },
    "filters": {
      "volume_usd": {
        "min": 5000
      },
      "source_type": "transfer"
    }
  }'

Similar transaction timing and patterns across addresses suggest coordinated activity.