Search Profiles - Formo Docs

Search and filter wallet profiles across your project with advanced filtering capabilities. You can look up an exact wallet address, run a free-text search across addresses and social fields, and combine that with structured filters in the request body.

Authentication

This endpoint requires authentication using a Workspace API Key with profiles:read permission. Include the API key in your request headers:

Authorization: Bearer <your_workspace_api_key>

The API key needs to have the read permission for profiles in the API settings. You can configure this in your workspace API key settings.

Query Parameters

`address`

Filter by a specific wallet address (exact match).

curl -sS -X GET \
  -H "Authorization: Bearer <your_workspace_api_key>" \
  "https://api.formo.so/v0/profiles?address=0x1234..."

`search`

Case-insensitive free-text search across wallet addresses and all supported social fields. This includes values from both global wallet profiles and project-scoped identify overrides.

curl -sS -X GET \
  -H "Authorization: Bearer <your_workspace_api_key>" \
  "https://api.formo.so/v0/profiles?search=bob_override"

`expand`

Comma-separated list of optional sections to include in each profile response. Supported values:

apps - DeFi app interactions and balances
chains - Per-chain activity metrics
tokens - Token holdings
labels - Wallet labels

curl -sS -X GET \
  -H "Authorization: Bearer <your_workspace_api_key>" \
  "https://api.formo.so/v0/profiles?expand=apps,chains,labels"

Expanding fields like chains, tokens, or apps increases response size and latency. The collections are capped at 50 items each.

`order_by`

Field to sort results by. Supported values:

last_onchain (default) - Last on-chain activity timestamp
first_onchain - First on-chain activity timestamp
net_worth_usd - Total net worth
updated_at - Last profile update timestamp
tx_count - Total transaction count
first_seen - First seen timestamp in your app
last_seen - Last seen timestamp in your app
num_sessions - Number of sessions
revenue - Total revenue
volume - Total volume
points - Total points

`order_dir`

Sort direction:

desc (default) - Descending order
asc - Ascending order

`page`

1-indexed page number to return.

Default: 1

`size`

Page size - number of profiles per page.

Default: 100
Maximum: 1000

Request Body (Filters)

The search endpoint supports rich filtering capabilities through a JSON request body. The body contains a filter object with conditions and logic.

Filter Schema

{
  "conditions": [
    {
      "field": "users.net_worth_usd",
      "op": "gt",
      "value": 1000
    }
  ],
  "logic": "and"
}

Field	Type	Description
`conditions`	array	Array of filter conditions
`logic`	string	How to combine conditions: `and` (all must match) or `or` (any must match). Default: `and`

Filter Condition

Each condition in the conditions array has:

Field	Type	Description
`field`	string	The field path to filter on (see Field Reference below)
`op`	string	The comparison operator
`value`	string \| number \| boolean \| array	The value to compare against
`scope`	string	(Optional) Only for token filters: `any` (wallet + protocols) or `protocol` (specific protocol only)
`appId`	string	(Optional) Only for token filters with `scope: "protocol"`. The DeFi protocol ID (e.g., `aave-v3`, `compound-v3`)

Operators

Operator	Description	Example
`eq`	Equals	`{"field": "users.device", "op": "eq", "value": "Desktop"}`
`neq`	Not equals	`{"field": "users.os", "op": "neq", "value": "Windows"}`
`gt`	Greater than	`{"field": "users.net_worth_usd", "op": "gt", "value": 1000}`
`gte`	Greater than or equal	`{"field": "users.volume", "op": "gte", "value": 100}`
`lt`	Less than	`{"field": "users.net_worth_usd", "op": "lt", "value": 50000}`
`lte`	Less than or equal	`{"field": "chains.1.balance", "op": "lte", "value": 10000}`
`in`	In array	`{"field": "users.lifecycle", "op": "in", "value": ["New", "Power user"]}`
`nin`	Not in array	`{"field": "users.location", "op": "nin", "value": ["US", "UK"]}`
`contains`	Case-insensitive substring match for social fields only	`{"field": "users.twitter", "op": "contains", "value": "vitalik"}`

Field Reference

User Fields (`users.*`)

Filter by user engagement and profile data. Use the format users.{attribute}.

Profile Fields

Field	Type	Description
`users.net_worth_usd`	number	Total net worth in USD
`users.volume`	number	Total trading volume
`users.revenue`	number	Total revenue
`users.points`	number	Total points

Example - Find users with net worth > $10,000:

{
  "conditions": [
    { "field": "users.net_worth_usd", "op": "gt", "value": 10000 }
  ],
  "logic": "and"
}

Example - Find high-volume users:

{
  "conditions": [
    { "field": "users.volume", "op": "gt", "value": 5000 }
  ],
  "logic": "and"
}

Engagement Fields

Field	Type	Description
`users.device`	string	Device type (e.g., `Desktop`, `Mobile`)
`users.browser`	string	Browser name (e.g., `Chrome`, `Safari`)
`users.os`	string	Operating system (e.g., `macOS`, `Windows`)
`users.location`	string	Country code (e.g., `US`, `NG`)

Example - Find mobile users from the US:

{
  "conditions": [
    { "field": "users.device", "op": "eq", "value": "Mobile" },
    { "field": "users.location", "op": "eq", "value": "US" }
  ],
  "logic": "and"
}

UTM & Referral Fields

Field	Type	Description
`users.first_utm_source`	string	First UTM source
`users.last_utm_source`	string	Last UTM source
`users.first_utm_medium`	string	First UTM medium
`users.last_utm_medium`	string	Last UTM medium
`users.first_utm_campaign`	string	First UTM campaign
`users.last_utm_campaign`	string	Last UTM campaign
`users.first_utm_content`	string	First UTM content
`users.last_utm_content`	string	Last UTM content
`users.first_utm_term`	string	First UTM term
`users.last_utm_term`	string	Last UTM term
`users.first_referrer`	string	First referrer domain
`users.last_referrer`	string	Last referrer domain
`users.first_referrer_url`	string	First referrer full URL
`users.last_referrer_url`	string	Last referrer full URL
`users.first_ref`	string	First referral code
`users.last_ref`	string	Last referral code

Example - Find users from Google Ads campaign:

{
  "conditions": [
    { "field": "users.first_utm_source", "op": "eq", "value": "google" },
    { "field": "users.first_utm_medium", "op": "eq", "value": "cpc" }
  ],
  "logic": "and"
}

Lifecycle Filter

Filter by user lifecycle stage. Valid values: Churned, New, Power user, Resurrected, Returning.

Field	Type	Description
`users.lifecycle`	string	User lifecycle stage

Example - Find new and power users:

{
  "conditions": [
    { "field": "users.lifecycle", "op": "in", "value": ["New", "Power user"] }
  ],
  "logic": "and"
}

Social fields support two modes:

Presence checks: use an empty string value to match profiles where the field is present.
Value matching: use eq, neq, or contains with a non-empty string to match the actual social value.

Field	Description
`users.ens`	ENS name
`users.farcaster`	Farcaster username
`users.lens`	Lens handle
`users.basenames`	Base names
`users.linea`	Linea identifier
`users.discord`	Discord username
`users.telegram`	Telegram username
`users.website`	Website URL
`users.twitter`	Twitter/X handle
`users.github`	GitHub username
`users.linkedin`	LinkedIn profile
`users.email`	Email address
`users.instagram`	Instagram handle
`users.facebook`	Facebook profile
`users.tiktok`	TikTok handle
`users.youtube`	YouTube channel or handle
`users.reddit`	Reddit username

Example - Find users with any email present:

{
  "conditions": [
    { "field": "users.email", "op": "eq", "value": "" }
  ],
  "logic": "and"
}

Example - Find users with both ENS and Farcaster present:

{
  "conditions": [
    { "field": "users.ens", "op": "eq", "value": "" },
    { "field": "users.farcaster", "op": "eq", "value": "" }
  ],
  "logic": "and"
}

Example - Find users whose Twitter contains bob:

{
  "conditions": [
    { "field": "users.twitter", "op": "contains", "value": "bob" }
  ],
  "logic": "and"
}

Example - Find an exact email match:

{
  "conditions": [
    { "field": "users.email", "op": "eq", "value": "alice@formo.so" }
  ],
  "logic": "and"
}

Chain Filters (`chains.*`)

Filter by per-chain net worth. Supports filtering across all chains or specific chains.

All Chains

Use chains.balance to filter across all chains (returns profiles where any chain matches). Example - Find users with >$1,000 on any chain:

{
  "conditions": [
    { "field": "chains.balance", "op": "gt", "value": 1000 }
  ],
  "logic": "and"
}

Specific Chain

Use chains.{chain_id}.balance to filter on a specific chain. Common chain IDs:

1 - Ethereum Mainnet
137 - Polygon
42161 - Arbitrum One
10 - Optimism
8453 - Base
56 - BNB Chain
43114 - Avalanche

Example - Find users with >$5,000 on Ethereum:

{
  "conditions": [
    { "field": "chains.1.balance", "op": "gt", "value": 5000 }
  ],
  "logic": "and"
}

Example - Find users with >$1,000 on both Ethereum and Polygon:

{
  "conditions": [
    { "field": "chains.1.balance", "op": "gt", "value": 1000 },
    { "field": "chains.137.balance", "op": "gt", "value": 1000 }
  ],
  "logic": "and"
}

App Filters (`apps.*`)

Filter by DeFi app interactions and balances.

All Chains

Use apps.{app_id}.balance to filter by app balance across all chains. Example - Find users with >$1,000 in Uniswap:

{
  "conditions": [
    { "field": "apps.uniswap.balance", "op": "gt", "value": 1000 }
  ],
  "logic": "and"
}

Specific Chain

Use apps.{chain_id}.{app_id}.balance to filter by app balance on a specific chain. Example - Find users with >$500 in Aave on Ethereum:

{
  "conditions": [
    { "field": "apps.1.aave.balance", "op": "gt", "value": 500 }
  ],
  "logic": "and"
}

Token Filters (`tokens.*`)

Filter by token holdings. Supports optional scope and appId parameters.

Token Filter Parameters

Parameter	Type	Description
`scope`	string	`any` (default) = wallet + all protocols, `protocol` = specific protocol only
`appId`	string	Only for `scope: "protocol"`. Specifies the DeFi protocol ID (e.g., `aave-v3`, `compound-v3`, `uniswap-v3`)

All Chains

Use tokens.{token_address}.balance to filter by token balance across all chains. Example - Find users holding >1000 USDC (any chain):

{
  "conditions": [
    {
      "field": "tokens.0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48.balance",
      "op": "gt",
      "value": 1000
    }
  ],
  "logic": "and"
}

Specific Chain

Use tokens.{chain_id}.{token_address}.balance to filter by token balance on a specific chain. Example - Find users with >500 USDC on Ethereum:

{
  "conditions": [
    {
      "field": "tokens.1.0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48.balance",
      "op": "gt",
      "value": 500
    }
  ],
  "logic": "and"
}

Protocol-Specific Token Filters

Use scope: "protocol" with appId to filter for tokens deposited in a specific DeFi protocol. Example - Find users with USDC deposited in any protocol:

{
  "conditions": [
    {
      "field": "tokens.0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48.balance",
      "op": "gt",
      "value": 0,
      "scope": "protocol"
    }
  ],
  "logic": "and"
}

Example - Find users with USDC deposited in Aave V3:

{
  "conditions": [
    {
      "field": "tokens.0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48.balance",
      "op": "gt",
      "value": 1000,
      "scope": "protocol",
      "appId": "aave-v3"
    }
  ],
  "logic": "and"
}

Example - Find users with ETH staked in Lido:

{
  "conditions": [
    {
      "field": "tokens.0x0000000000000000000000000000000000000000.balance",
      "op": "gt",
      "value": 1,
      "scope": "protocol",
      "appId": "lido"
    }
  ],
  "logic": "and"
}

Label Filters (`labels.*`)

Filter by wallet labels. Use the format labels.{tag_id}. Common label IDs:

coinbase.verified_account - Coinbase verified account (boolean)
coinbase.verified_country - Coinbase verified country code
coinbase.verified_coinbase_one - Coinbase One membership (boolean)
sanctions.designated - Sanctioned address (boolean)
passport.models_aggregate_score - Passport aggregate score (0-100)
passport.unique_humanity_score - Passport uniqueness score

Example - Find Coinbase verified users:

{
  "conditions": [
    { "field": "labels.coinbase.verified_account", "op": "eq", "value": "true" }
  ],
  "logic": "and"
}

Example - Find US-verified Coinbase users:

{
  "conditions": [
    { "field": "labels.coinbase.verified_country", "op": "eq", "value": "US" }
  ],
  "logic": "and"
}

Example - Find users with high Passport score:

{
  "conditions": [
    { "field": "labels.passport.models_aggregate_score", "op": "gte", "value": "50" }
  ],
  "logic": "and"
}

Combined Filter Examples

High-Value Web3 Users

Find users with >$10,000 net worth, ENS name, and activity on Ethereum:

curl -sS -X GET \
  -H "Authorization: Bearer <your_workspace_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "conditions": [
      { "field": "users.net_worth_usd", "op": "gt", "value": 10000 },
      { "field": "users.ens", "op": "eq", "value": true },
      { "field": "chains.1.balance", "op": "gt", "value": 0 }
    ],
    "logic": "and"
  }' \
  "https://api.formo.so/v0/profiles?expand=chains,labels"

Active DeFi Users

Find users with activity in Uniswap or Aave:

curl -sS -X GET \
  -H "Authorization: Bearer <your_workspace_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "conditions": [
      { "field": "apps.uniswap.balance", "op": "gt", "value": 0 },
      { "field": "apps.aave.balance", "op": "gt", "value": 0 }
    ],
    "logic": "or"
  }' \
  "https://api.formo.so/v0/profiles?expand=apps"

Verified Power Users

Find Coinbase-verified power users from specific countries:

curl -sS -X GET \
  -H "Authorization: Bearer <your_workspace_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "conditions": [
      { "field": "labels.coinbase.verified_account", "op": "eq", "value": "true" },
      { "field": "labels.coinbase.verified_country", "op": "in", "value": ["US", "UK", "DE"] },
      { "field": "users.lifecycle", "op": "eq", "value": "Power user" }
    ],
    "logic": "and"
  }' \
  "https://api.formo.so/v0/profiles"

Multi-Chain Whales

Find users with significant holdings across multiple chains:

curl -sS -X GET \
  -H "Authorization: Bearer <your_workspace_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "conditions": [
      { "field": "chains.1.balance", "op": "gt", "value": 10000 },
      { "field": "chains.137.balance", "op": "gt", "value": 5000 },
      { "field": "chains.42161.balance", "op": "gt", "value": 5000 }
    ],
    "logic": "and"
  }' \
  "https://api.formo.so/v0/profiles?expand=chains&order_by=net_worth_usd&order_dir=desc"

Response

The response is a paginated envelope of wallet profiles.

{
  "data": [
    {
      "address": "0x9CC3cB28cd94eB4423B15cdA73346e204f59a407",
      "net_worth_usd": 125000.5,
      "ens": "example.eth",
      "tx_count": 1234,
      "first_onchain": "2024-01-15T10:30:00Z",
      "last_onchain": "2025-01-20T14:22:00Z",
      "lifecycle": "Returning"
    }
  ],
  "total": 150,
  "page": 1,
  "size": 100,
  "has_more": true
}

Response Fields

Field	Type	Description
`data`	array	Array of wallet profiles matching the search criteria
`total`	integer	Total number of profiles matching the criteria across all pages
`page`	integer	1-indexed page number echoed from the request
`size`	integer	Page size echoed from the request
`has_more`	boolean	`true` if there are pages after the current one

Profile Fields

Each profile in the data array includes:

Field	Type	Description
`address`	string	Wallet address
`net_worth_usd`	number	Total net worth in USD
`tx_count`	integer	Total transaction count
`first_onchain`	string	First on-chain activity timestamp (ISO 8601)
`last_onchain`	string	Last on-chain activity timestamp (ISO 8601)
`lifecycle`	string	User lifecycle stage: `Churned`, `New`, `Power user`, `Resurrected`, `Returning`
`ens`	string \| null	ENS name
`farcaster`	string \| null	Farcaster username
`twitter`	string \| null	Twitter/X handle
`discord`	string \| null	Discord username
`telegram`	string \| null	Telegram username
`email`	string \| null	Email address
`first_seen`	string \| null	First seen timestamp in your app
`last_seen`	string \| null	Last seen timestamp in your app
`num_sessions`	integer \| null	Total number of sessions
`revenue`	number \| null	Total revenue
`volume`	number \| null	Total volume
`points`	number \| null	Total points
`chains`	array \| null	Per-chain data (when expanded)
`apps`	array \| null	DeFi app data (when expanded)
`tokens`	array \| null	Token holdings (when expanded)
`labels`	array \| null	Wallet labels (when expanded)

Error Responses

Status	Code	Description
400	`BAD_REQUEST`	Invalid query parameters or malformed JSON in request body
401	`UNAUTHORIZED`	Missing or invalid API key
403	`FORBIDDEN`	API key does not have `profiles:read` permission
500	`INTERNAL_SERVER_ERROR`	Failed to fetch wallet profile data

Authorizations

Authorization

string

header

required

Workspace API key (e.g. formo_xxx). Create one in the Formo dashboard under Team Settings > API Keys.

Query Parameters

address

string

Filter by wallet address

expand

string

Comma-separated: apps, chains, tokens, labels

order_by

enum<string>

Sort field

Available options:

net_worth_usd,

tx_count,

first_onchain,

last_onchain,

updated_at,

first_seen,

last_seen,

num_sessions,

revenue,

volume,

points

order_dir

enum<string>

Sort direction

Available options:

asc,

desc

page

integer

default:1

1-indexed page number (default 1).

Required range: x >= 1

size

integer

default:100

Page size (default 100, max 1000).

Required range: 1 <= x <= 1000

Body

application/json

Optional filter conditions

Filter conditions for profile search

conditions

object[]

Show child attributes

logic

enum<string>

default:and

Available options:

and,

or

Response

Paginated wallet profile search results.

Pagination cursor returned alongside data on every paginated list endpoint. Use these to walk pages: has_more is true while page * size < total. Combine with the matching Page and Size query parameters to request the next page.

page

integer

required

1-indexed page number echoed from the request.

size

integer

required

Page size echoed from the request.

total

integer

required

Total row count across all pages.

has_more

boolean

required

True when more pages remain (page * size < total).

data

object[]

required

Show child attributes

API Documentation

Events API

Profiles API

Query API

Charts API

Segments API

Contracts API

Alerts API

Documentation Index

​Authentication

​Query Parameters

​address

​search

​expand

​order_by

​order_dir

​page

​size

​Request Body (Filters)

​Filter Schema

​Filter Condition

​Operators

​Field Reference

​User Fields (users.*)

​Profile Fields

​Engagement Fields

​UTM & Referral Fields

​Lifecycle Filter

​Social Fields

​Chain Filters (chains.*)

​All Chains

​Specific Chain

​App Filters (apps.*)

​All Chains

​Specific Chain

​Token Filters (tokens.*)

​Token Filter Parameters

​All Chains

​Specific Chain

​Protocol-Specific Token Filters

​Label Filters (labels.*)

​Combined Filter Examples

​High-Value Web3 Users

​Active DeFi Users

​Verified Power Users

​Multi-Chain Whales

​Response

​Response Fields

​Profile Fields

​Error Responses

Authorizations

Query Parameters

Body

Response

Authentication

Query Parameters

`address`

`search`

`expand`

`order_by`

`order_dir`

`page`

`size`

Request Body (Filters)

Filter Schema

Filter Condition

Operators

Field Reference

User Fields (`users.*`)

Profile Fields

Engagement Fields

UTM & Referral Fields

Lifecycle Filter

Social Fields

Chain Filters (`chains.*`)

All Chains

Specific Chain

App Filters (`apps.*`)

All Chains

Specific Chain

Token Filters (`tokens.*`)

Token Filter Parameters

All Chains

Specific Chain

Protocol-Specific Token Filters

Label Filters (`labels.*`)

Combined Filter Examples

High-Value Web3 Users

Active DeFi Users

Verified Power Users

Multi-Chain Whales

Response

Response Fields

Profile Fields

Error Responses