Wallet addresses tell you more about a user than any cookie ever could. Transaction history, holdings, DeFi positions, protocol preferences — it's all there, permanently and publicly on-chain. The challenge isn't finding the data; it's structuring it into profiles you can actually act on.

This guide walks through the full process: SDK setup, event mapping, a recommended profile schema, identity clustering, API examples, privacy compliance, and a growth playbook to turn profiles into campaigns.

Quickstart: SDK setup and configuration

Before you can build profiles, you need event data flowing from your dApp. Formo's SDK instruments both offchain behaviour (page views, clicks, form submissions) and onchain events (wallet connects, transactions, smart contract calls) from a single integration.

Install the SDK

npm

npm

npm

Initialise in your app

import { Formo } from '@formo/analytics';

const formo = new Formo({
  apiKey: 'YOUR_API_KEY',
  options: {
    trackWalletConnect: true,  // auto-capture wallet connection events
    trackOnchainEvents: true,  // index smart contract interactions
    privacyMode: 'pseudonymous' // never collect raw PII
  }
});

import { Formo } from '@formo/analytics';

const formo = new Formo({
  apiKey: 'YOUR_API_KEY',
  options: {
    trackWalletConnect: true,  // auto-capture wallet connection events
    trackOnchainEvents: true,  // index smart contract interactions
    privacyMode: 'pseudonymous' // never collect raw PII
  }
});

import { Formo } from '@formo/analytics';

const formo = new Formo({
  apiKey: 'YOUR_API_KEY',
  options: {
    trackWalletConnect: true,  // auto-capture wallet connection events
    trackOnchainEvents: true,  // index smart contract interactions
    privacyMode: 'pseudonymous' // never collect raw PII
  }
});

Identify a user when they connect their wallet

// Called after wallet connect
formo.identify(walletAddress, {
  twitter: await resolveENS(twitterUserName), // optional off-chain enrichment
  referralSource: utmParams.source, // other properties
});

// Called after wallet connect
formo.identify(walletAddress, {
  twitter: await resolveENS(twitterUserName), // optional off-chain enrichment
  referralSource: utmParams.source, // other properties
});

// Called after wallet connect
formo.identify(walletAddress, {
  twitter: await resolveENS(twitterUserName), // optional off-chain enrichment
  referralSource: utmParams.source, // other properties
});

The identify call is the anchor point for the wallet profile. Every subsequent event — page view, swap, liquidity deposit — gets attributed to that address.

Formo's SDK is open-source under the MIT licence and works across Ethereum, Solana, and 30+ chains without requiring a separate node infrastructure.

Sample profile data model

A wallet profile is a structured document that accumulates over time. Below is a recommended schema covering the five core data categories:

{
  "wallet_address": "0xABCD...1234",
  "chain_id": 1,
  "profile_id": "usr_xyz",
  "identity": {
    "ens_name": "alice.eth",
    "linked_addresses": ["0xABCD...1234", "0x9876...DCBA"],
    "confidence_score": 0.91,
    "labels": ["whale", "defi_power_user", "lp_provider"]
  },
  "demographics": {
    "wallet_age_days": 892,
    "country": "SG",
    "device": "desktop",
    "traffic_source": "organic_search"
  },
  "onchain_activity": {
    "total_tx_count": 1240,
    "last_active": "2026-04-28T10:22:00Z",
    "protocols_used": ["Uniswap", "Aave", "Curve"],
    "chains_active": [1, 8453, 42161],
    "net_worth_usd": 84200,
    "tx_volume_30d_usd": 12500
  },
  "product_usage": {
    "sessions_30d": 14,
    "key_actions": ["swap", "deposit", "governance_vote"],
    "funnel_stage": "active"
  },
  "community_signals": {
    "discord_handle": "alice#0001",
    "twitter_handle": "@alice_defi",
    "governance_votes": 7
  },
  "attribution": {
    "first_touch_channel": "twitter_ad",
    "utm_source": "twitter",
    "utm_campaign": "lp_launch_q1",
    "converted_at": "2026-01-15T08:44:00Z"
  }
}

{
  "wallet_address": "0xABCD...1234",
  "chain_id": 1,
  "profile_id": "usr_xyz",
  "identity": {
    "ens_name": "alice.eth",
    "linked_addresses": ["0xABCD...1234", "0x9876...DCBA"],
    "confidence_score": 0.91,
    "labels": ["whale", "defi_power_user", "lp_provider"]
  },
  "demographics": {
    "wallet_age_days": 892,
    "country": "SG",
    "device": "desktop",
    "traffic_source": "organic_search"
  },
  "onchain_activity": {
    "total_tx_count": 1240,
    "last_active": "2026-04-28T10:22:00Z",
    "protocols_used": ["Uniswap", "Aave", "Curve"],
    "chains_active": [1, 8453, 42161],
    "net_worth_usd": 84200,
    "tx_volume_30d_usd": 12500
  },
  "product_usage": {
    "sessions_30d": 14,
    "key_actions": ["swap", "deposit", "governance_vote"],
    "funnel_stage": "active"
  },
  "community_signals": {
    "discord_handle": "alice#0001",
    "twitter_handle": "@alice_defi",
    "governance_votes": 7
  },
  "attribution": {
    "first_touch_channel": "twitter_ad",
    "utm_source": "twitter",
    "utm_campaign": "lp_launch_q1",
    "converted_at": "2026-01-15T08:44:00Z"
  }
}

{
  "wallet_address": "0xABCD...1234",
  "chain_id": 1,
  "profile_id": "usr_xyz",
  "identity": {
    "ens_name": "alice.eth",
    "linked_addresses": ["0xABCD...1234", "0x9876...DCBA"],
    "confidence_score": 0.91,
    "labels": ["whale", "defi_power_user", "lp_provider"]
  },
  "demographics": {
    "wallet_age_days": 892,
    "country": "SG",
    "device": "desktop",
    "traffic_source": "organic_search"
  },
  "onchain_activity": {
    "total_tx_count": 1240,
    "last_active": "2026-04-28T10:22:00Z",
    "protocols_used": ["Uniswap", "Aave", "Curve"],
    "chains_active": [1, 8453, 42161],
    "net_worth_usd": 84200,
    "tx_volume_30d_usd": 12500
  },
  "product_usage": {
    "sessions_30d": 14,
    "key_actions": ["swap", "deposit", "governance_vote"],
    "funnel_stage": "active"
  },
  "community_signals": {
    "discord_handle": "alice#0001",
    "twitter_handle": "@alice_defi",
    "governance_votes": 7
  },
  "attribution": {
    "first_touch_channel": "twitter_ad",
    "utm_source": "twitter",
    "utm_campaign": "lp_launch_q1",
    "converted_at": "2026-01-15T08:44:00Z"
  }
}

Keep the schema flexible. New fields — governance participation, NFT holdings, cross-chain positions — can be added incrementally as your data pipeline matures. Start with the identity, onchain activity, and attribution blocks; add community signals once you have the offchain data pipeline connected.

Event mapping: offchain and onchain → profile attributes

Every event your dApp emits maps to one or more profile fields. Getting this mapping right is the difference between a profile that supports useful segmentation and one that's just a collection of timestamps.

Offchain events (tracked via SDK)

Onchain events (indexed from chain)

To capture a custom event:

formo.track('swap_executed', {
  wallet_address: connectedWallet,
  token_in: 'USDC',
  token_out: 'ETH',
  amount_usd: 1500,
  protocol: 'Uniswap',
  chain_id: 1
});

formo.track('swap_executed', {
  wallet_address: connectedWallet,
  token_in: 'USDC',
  token_out: 'ETH',
  amount_usd: 1500,
  protocol: 'Uniswap',
  chain_id: 1
});

formo.track('swap_executed', {
  wallet_address: connectedWallet,
  token_in: 'USDC',
  token_out: 'ETH',
  amount_usd: 1500,
  protocol: 'Uniswap',
  chain_id: 1
});

Formo's web3 event tracking handbook covers standardised event schemas for DeFi in more detail.

Identity resolution and clustering

Most active DeFi users operate multiple wallets — a hot wallet for daily trades, a cold wallet for long-term holdings, a separate address for protocol-specific activity. Without clustering, each address looks like a different user. With it, you get an accurate count of actual people.

Common clustering heuristics

1. Shared funding source — Two addresses both received their first ETH from the same CEX withdrawal or the same originating address. This is the strongest signal of common ownership.

2. Temporal co-movement — Addresses that execute transactions within seconds of each other, especially on the same protocols, often share a controller.

3. Gas refill pattern — A single address consistently tops up gas for a set of other addresses, suggesting a single entity managing multiple wallets.

4. ENS and social linking — A user signs a message with multiple wallets to prove ownership, or an ENS name resolves to a primary address that cross-references others.

5. Consented linking — The highest-confidence signal: a user connects multiple wallets in your app explicitly, or signs into a token-gated form with different addresses.

Confidence scoring

Assign a confidence score to each clustered identity:

Profiles with a score above 0.80 can be merged for growth targeting. Scores between 0.50 and 0.80 should be flagged for review. Below 0.50, keep addresses separate.

Bot and Sybil detection

Before merging or activating profiles, run a quick check:

• Wallet age under 7 days with high transaction velocity → likely farmer

• Identical transaction sequences across multiple addresses → Sybil cluster

• Funded by known dispersion contracts → flag for review

Sybil wallets captured nearly half the distributed tokens in the Arbitrum airdrop — clean data is worth the effort. Formo applies automated Sybil detection to filter bot clusters before they distort your segments.

Profiles API: read, update, export

Once profiles are built, you can query and act on them via Formo's open API.

Get a single profile

curl -X GET https://api.formo.so/v1/profiles/0xABCD...1234 \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X GET https://api.formo.so/v1/profiles/0xABCD...1234 \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X GET https://api.formo.so/v1/profiles/0xABCD...1234 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "wallet_address": "0xABCD...1234",
  "identity": { "labels": ["whale", "lp_provider"], "confidence_score": 0.91 },
  "onchain_activity": { "last_active": "2026-04-28", "tx_volume_30d_usd": 12500 },
  "funnel_stage": "active"
}

{
  "wallet_address": "0xABCD...1234",
  "identity": { "labels": ["whale", "lp_provider"], "confidence_score": 0.91 },
  "onchain_activity": { "last_active": "2026-04-28", "tx_volume_30d_usd": 12500 },
  "funnel_stage": "active"
}

{
  "wallet_address": "0xABCD...1234",
  "identity": { "labels": ["whale", "lp_provider"], "confidence_score": 0.91 },
  "onchain_activity": { "last_active": "2026-04-28", "tx_volume_30d_usd": 12500 },
  "funnel_stage": "active"
}

Update a profile attribute

curl -X PATCH https://api.formo.so/v1/profiles/0xABCD...1234 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"community_signals": {"discord_handle": "alice#0001"}}'

curl -X PATCH https://api.formo.so/v1/profiles/0xABCD...1234 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"community_signals": {"discord_handle": "alice#0001"}}'

curl -X PATCH https://api.formo.so/v1/profiles/0xABCD...1234 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"community_signals": {"discord_handle": "alice#0001"}}'

Export a segment to CSV or webhook

curl -X POST https://api.formo.so/v1/segments/export \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      {"field": "identity.labels", "operator": "contains", "value": "lp_provider"},
      {"field": "onchain_activity.last_active", "operator": "gte", "value": "2026-03-01"}
    ],
    "format": "csv",
    "destination": "https://your-webhook.io/endpoint"
  }'

curl -X POST https://api.formo.so/v1/segments/export \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      {"field": "identity.labels", "operator": "contains", "value": "lp_provider"},
      {"field": "onchain_activity.last_active", "operator": "gte", "value": "2026-03-01"}
    ],
    "format": "csv",
    "destination": "https://your-webhook.io/endpoint"
  }'

curl -X POST https://api.formo.so/v1/segments/export \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      {"field": "identity.labels", "operator": "contains", "value": "lp_provider"},
      {"field": "onchain_activity.last_active", "operator": "gte", "value": "2026-03-01"}
    ],
    "format": "csv",
    "destination": "https://your-webhook.io/endpoint"
  }'

The open API supports arbitrary filtering, sorting, and pagination so you can pipe profiles directly into CRMs, Discord bots, email tools, or custom dashboards. Full reference is in the Formo API docs.

Privacy and consent checklist

Onchain data is public but not consequence-free. The moment you link a wallet address to an email, Discord handle, or social account, you're creating a record that can trigger GDPR obligations in Europe and similar frameworks elsewhere.

In June 2025, the European Data Protection Board adopted its first guidelines on processing personal data through blockchain technologies, confirming that enriched wallet profiles which link to identifiable individuals are subject to GDPR.

Before going live, verify each item:

• Data minimisation — Are you collecting only what you actually use? Don't store social handles if you're not sending comms.

• Consent mechanism — If you're linking a wallet to a Discord or email, show an explicit opt-in. Store the consent event with a timestamp.

• Purpose limitation — Document what each profile field is used for. Don't repurpose analytics data for compliance checks without re-consenting.

• Data subject rights — Can a user request deletion of their offchain profile data? (Onchain transaction data cannot be deleted, but your enrichment store can be.)

• Retention limits — Define how long you keep enrichment data. 90 days is a reasonable default for marketing data; extend to 5 years only for AML/KYC records where legally required.

• DPIA completed — High-risk processing (e.g., re-identifying pseudonymous addresses at scale) likely requires a Data Protection Impact Assessment.

• Privacy notice published — Your policy should name every data category, its legal basis, and retention period.

Sample consent text for wallet-to-social linking:

By connecting your Discord account, you agree that [Protocol Name] will link your Discord handle to your wallet address (0x…) to personalise your experience and send you product updates. You can withdraw this at any time from your account settings. We will not share this data with third parties. See our [Privacy Policy] for full details.

Formo is built without third-party cookies and avoids collecting raw PII by design — pseudonymous wallet addresses are the default identifier. See more on privacy-first Web3 analytics for implementation guidance.

Growth playbook: create a segment and run a campaign

Wallet profiles are only useful if they drive action. Here's a concrete example: re-engaging liquidity providers who have been dormant for 30+ days.

Step 1: Define the segment

In Formo's Chartbuilder or via the API, create a dynamic segment:

• Label: lp_provider

• Last active: more than 30 days ago

• Net worth: greater than $5,000 (high-value filter)

• Chain: Base or Arbitrum

This segment auto-updates as wallets move in or out of the criteria.

Step 2: Enrich with contact handles

Query the segment for Discord handles and ENS names collected via your token-gated waitlist or survey. Wallets with linked handles become reachable; the rest can be targeted via onchain mechanisms (airdrop, NFT-gated access).

Step 3: Launch the campaign

Export the segment to your outreach tool. For Discord: send a personalised DM referencing the user's last protocol interaction. For email: use the wallet's transaction volume as personalisation context.

Example message:

Hey Alice — you deposited $12K to Curve on Base back in March. We've just launched a new yield strategy on the same pair with 18% APY. Your position is ready to re-activate.

Step 4: Measure onchain outcomes

Don't measure open rates. Measure:

• Wallet reconnects within 7 days of campaign send

• Liquidity deposits within 14 days (onchain conversion)

• Volume reactivated (USD)

• CAC for this cohort vs. your new-user average

Formo's onchain attribution links campaign sends to downstream transactions so you can see actual ROI, not proxy metrics.

Segment ideas to test immediately

For a deeper walkthrough of segment design, the Web3 user segmentation guide covers lifecycle stages, behavioural cohorts, and DeFi-native criteria in detail.

FAQs

What is a wallet profile?

A wallet profile gives you a unified view of a user's onchain activity by linking all their wallet addresses. It includes transaction history, token and NFT holdings, DeFi positions, and app interactions. Teams use profiles for analytics to understand user behaviour and personalise experiences across Web3.

How do wallet profiles differ from traditional user profiles?

Wallet profiles use a pseudonymous wallet address as the identifier rather than an email or username. The data is portable across apps, and much of it is observable before a user ever signs into your product. Web2 profiles, by contrast, are locked into the platform that collected them.

Are wallet profiles compliant with GDPR and privacy regulations?

Pure onchain data is public, so GDPR doesn't restrict your use of it. The obligation arises when you link addresses to personal data (emails, social handles, names). At that point, you need a lawful basis for processing, a privacy notice, a consent mechanism, and a way for users to request deletion of the offchain portion. The EDPB's 2025 blockchain guidelines are the current reference for EU compliance.

How are wallet profiles created?

Profiles are built by identifying a wallet address, collecting onchain data via indexers, instrumenting offchain events via an SDK, and then running identity resolution to cluster related addresses. Offchain enrichment (ENS, social handles, attribution data) is layered on top to make profiles more actionable.

What are the main use cases for wallet profiles in growth work?

Activation campaigns for wallets that connected but never transacted, re-engagement of dormant liquidity providers, personalised onboarding flows, airdrop quality scoring (filtering Sybil wallets), and CAC/LTV analysis by acquisition channel are the most common.

What data sources are used to build wallet profiles?

Onchain: blockchain indexers, RPC nodes, protocol subgraphs. Offchain: product analytics SDKs, ENS resolvers, social handle databases, CRM data, and attribution UTM parameters. Providers like Moralis, Zerion API, and Alchemy cover the onchain data layer; Formo unifies both into a single profile.

How do you detect and handle bot and Sybil wallets in profiles?

Common signals include very new wallets with high transaction velocity, identical transaction sequences across multiple addresses, and funding from known dispersion contracts. Automated labelling flags suspicious wallets before they reach your growth segments. Keeping bots out of your segments is critical — inflated wallet counts lead to wasted campaign spend and misleading retention metrics.

What are the best practices for keeping wallet profiles accurate?

Run identity resolution on a regular cadence (weekly for active segments), check for new cross-chain activity across the chains your users are active on, review clustering confidence scores periodically to catch false positives, and define whether each profile represents a single address or a merged entity so downstream analytics stay consistent.