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 settings.

Query Parameters

`address`

Filter by a specific wallet address (exact match). Accepts an EVM address, a Solana address, or an ENS name (e.g. vitalik.eth) which is resolved to an address before filtering. An unresolvable ENS name or an otherwise invalid value returns a 400 BAD_REQUEST.

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

# ENS names are resolved automatically
curl -sS -X GET \
  -H "Authorization: Bearer <your_workspace_api_key>" \
  "https://api.formo.so/v0/profiles?address=vitalik.eth"

`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 filters and logic.

Filter Schema

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

Field	Type	Description
`filters`	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 filter in the filters array carries the canonical {field, op, value} core, plus named qualifier properties for resource filters:

Field	Type	Description
`field`	string	The stable field path to filter on (see Field Reference below). User/profile/social fields use `users.{attribute}`. Resource metrics use the fixed paths `chains.balance`, `apps.balance`, `tokens.balance`, or `labels.value`. Identifiers belong in the qualifier properties below and must not be embedded in the field path.
`op`	string	The comparison operator
`value`	string \| number \| boolean \| array	The value to compare against. Balance fields (`chains.balance`, `apps.balance`, `tokens.balance`) require a JSON number; numeric strings and empty strings are rejected. `labels.value` rejects an empty string.
`chain_id`	string	(Optional) Chain qualifier for `chains.balance`, `apps.balance`, `tokens.balance`, and `labels.value`. Omit to compare across all chains.
`app_id`	string	Required for `apps.balance`, and for `tokens.balance` with `scope: "protocol"` (e.g., `aave-v3`, `compound-v3`).
`token_address`	string	Required token address for `tokens.balance`.
`scope`	string	Required for `tokens.balance`: `any` (wallet + all protocols) or `protocol` (a specific protocol; requires `app_id`).
`tag_id`	string	Required label tag for `labels.value` (e.g., `coinbase.verified_account`).

Unknown properties and qualifiers that don’t apply to the targeted field are rejected with a 400.

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.balance", "op": "lte", "value": 10000, "chain_id": "1"}`
`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 and `labels.value`	`{"field": "users.twitter", "op": "contains", "value": "vitalik"}`
`notEmpty`	Field is set (non-empty). String fields only; value is ignored	`{"field": "users.email", "op": "notEmpty"}`
`isEmpty`	Field is not set (empty). String user attributes only; value is ignored	`{"field": "users.utm_source", "op": "isEmpty"}`

Behavioural labels such as defi.lender, defi.borrower, defi.staker and defi.perp_trader store a USD amount as their value, so the comparison operators work on them. For example, wallets that supply at least $10,000 to lending markets: {"field": "labels.value", "op": "gte", "value": "10000", "tag_id": "defi.lender"}. See Wallet labels for the full list and each label’s rule.

Legacy spellings are retired. The long-form spellings equals, notEquals, greater, greaterOrEqual, less, lessOrEqual, notIn, and includes (and symbol forms like = / != / like) are no longer accepted on this endpoint. A request carrying one is rejected with a 400 whose message names the offending token. Send only the canonical operators above. notEmpty / isEmpty are value-less existence checks (any value is ignored) and are supported on string user/profile attributes only, not on numeric metrics (net_worth_usd, volume, revenue, points), the lifecycle enum, or chain/app/token/label fields.

Dynamic field paths are retired. Identifier-in-path spellings such as chains.1.balance, apps.aave-v3.balance, tokens.0x….balance, and labels.coinbase.verified_account are no longer accepted and return a 400. Use the stable field (chains.balance, apps.balance, tokens.balance, labels.value) with the matching qualifier property (chain_id, app_id, token_address, tag_id) instead. Balance fields support only the comparison operators (eq, neq, gt, gte, lt, lte); labels.value supports comparisons plus case-insensitive contains.

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:

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

Example - Find high-volume users:

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

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

{
  "filters": [
    { "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: New, Returning, Power user, At Risk, Churned, Resurrected.

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

Example - Find new and power users:

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

Social fields support two modes:

Presence checks: use notEmpty to match profiles where the field is set (or isEmpty for the opposite). The value is ignored.
Value matching: use eq, neq, or contains (case-insensitive substring) 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:

{
  "filters": [
    { "field": "users.email", "op": "notEmpty" }
  ],
  "logic": "and"
}

Example - Find users with both ENS and Farcaster present:

{
  "filters": [
    { "field": "users.ens", "op": "notEmpty" },
    { "field": "users.farcaster", "op": "notEmpty" }
  ],
  "logic": "and"
}

Example - Find users whose Twitter contains bob:

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

Example - Find an exact email match:

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

Chain Filters (`chains.balance`)

Filter by per-chain net worth using the stable field chains.balance and an optional chain_id qualifier. This is distinct from users.net_worth_usd, which compares the profile’s total net worth.

All Chains

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

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

Specific Chain

Set the chain_id qualifier 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:

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

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

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

App Filters (`apps.balance`)

Filter by DeFi app balances using the stable field apps.balance with a required app_id qualifier and an optional chain_id qualifier.

All Chains

Omit chain_id to filter by app balance across all chains. Example - Find users with >$1,000 in Uniswap:

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

Specific Chain

Set the chain_id qualifier to filter by app balance on a specific chain. Example - Find users with >$500 in Aave on Ethereum:

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

Token Filters (`tokens.balance`)

Filter by token holdings using the stable field tokens.balance with required token_address and scope qualifiers, plus an optional chain_id and, for protocol scope, a required app_id.

Token Filter Qualifiers

Qualifier	Type	Description
`token_address`	string	Required. The token’s contract address.
`scope`	string	Required. `any` = wallet + all protocols, `protocol` = a specific protocol only (requires `app_id`)
`app_id`	string	Required for `scope: "protocol"`. The DeFi protocol ID (e.g., `aave-v3`, `compound-v3`, `uniswap-v3`)
`chain_id`	string	Optional. Omit to compare across all chains.

All Chains

Omit chain_id to filter by token balance across all chains. Example - Find users holding >1000 USDC (any chain):

{
  "filters": [
    {
      "field": "tokens.balance",
      "op": "gt",
      "value": 1000,
      "token_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "scope": "any"
    }
  ],
  "logic": "and"
}

Specific Chain

Set the chain_id qualifier to filter by token balance on a specific chain. Example - Find users with >500 USDC on Ethereum:

{
  "filters": [
    {
      "field": "tokens.balance",
      "op": "gt",
      "value": 500,
      "token_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "scope": "any",
      "chain_id": "1"
    }
  ],
  "logic": "and"
}

Protocol-Specific Token Filters

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

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

Example - Find users with ETH staked in Lido:

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

Label Filters (`labels.value`)

Filter by wallet labels using the stable field labels.value with a required tag_id qualifier (and an optional chain_id). Supported operators are the comparisons (eq, neq, gt, gte, lt, lte) and case-insensitive contains; the value must be non-empty. Common label tags:

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:

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

Example - Find US-verified Coinbase users:

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

Example - Find users with high Passport score:

{
  "filters": [
    { "field": "labels.value", "op": "gte", "value": 50, "tag_id": "passport.models_aggregate_score" }
  ],
  "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 '{
    "filters": [
      { "field": "users.net_worth_usd", "op": "gt", "value": 10000 },
      { "field": "users.ens", "op": "notEmpty" },
      { "field": "chains.balance", "op": "gt", "value": 0, "chain_id": "1" }
    ],
    "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 '{
    "filters": [
      { "field": "apps.balance", "op": "gt", "value": 0, "app_id": "uniswap" },
      { "field": "apps.balance", "op": "gt", "value": 0, "app_id": "aave" }
    ],
    "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 '{
    "filters": [
      { "field": "labels.value", "op": "eq", "value": "true", "tag_id": "coinbase.verified_account" },
      { "field": "labels.value", "op": "eq", "value": "US", "tag_id": "coinbase.verified_country" },
      { "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 '{
    "filters": [
      { "field": "chains.balance", "op": "gt", "value": 10000, "chain_id": "1" },
      { "field": "chains.balance", "op": "gt", "value": 5000, "chain_id": "137" },
      { "field": "chains.balance", "op": "gt", "value": 5000, "chain_id": "42161" }
    ],
    "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 filters
`total`	integer	Total number of profiles matching the filters 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: `New`, `Returning`, `Power user`, `At Risk`, `Churned`, `Resurrected`
`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.

Query Parameters

address

string

Filter by wallet address. Accepts an EVM (0x...) or Solana address, or an ENS name (e.g. vitalik.eth) which is resolved to an address.

expand

string

Comma-separated: apps, chains, tokens, labels

timestamp

string<date-time>

Optional point in time for wallet-enrichment data. Requires the address query parameter; unbounded historical collection scans are rejected. Returns the wallet's stored base snapshot closest to this instant instead of its latest snapshot; an exact-distance tie chooses the later snapshot. Expanded chains, apps, and tokens come from the selected snapshot's profiling batch. Project engagement fields, project-defined identity overrides, and labels remain current. Must be ISO-8601 with a timezone.

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

A profile-search filter group. filters contains canonical {field, op, value} leaves and logic combines them at this level.

filters

object[]

required

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

​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.balance)

​All Chains

​Specific Chain

​App Filters (apps.balance)

​All Chains

​Specific Chain

​Token Filters (tokens.balance)

​Token Filter Qualifiers

​All Chains

​Specific Chain

​Protocol-Specific Token Filters

​Label Filters (labels.value)

​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.balance`)

All Chains

Specific Chain

App Filters (`apps.balance`)

All Chains

Specific Chain

Token Filters (`tokens.balance`)

Token Filter Qualifiers

All Chains

Specific Chain

Protocol-Specific Token Filters

Label Filters (`labels.value`)

Combined Filter Examples

High-Value Web3 Users

Active DeFi Users

Verified Power Users

Multi-Chain Whales

Response

Response Fields

Profile Fields

Error Responses