Search Profiles - Formo Docs

curl --request GET \
  --url https://api.formo.so/v0/profiles \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "conditions": [
    {
      "field": "users.net_worth_usd",
      "op": "gt",
      "value": 10000
    }
  ],
  "logic": "and"
}
'

{
  "data": [
    {
      "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "net_worth_usd": 12345.67
    }
  ],
  "page": 1,
  "size": 100,
  "total": 1,
  "has_more": false
}

GET

profiles

curl --request GET \
  --url https://api.formo.so/v0/profiles \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "conditions": [
    {
      "field": "users.net_worth_usd",
      "op": "gt",
      "value": 10000
    }
  ],
  "logic": "and"
}
'

{
  "data": [
    {
      "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "net_worth_usd": 12345.67
    }
  ],
  "page": 1,
  "size": 100,
  "total": 1,
  "has_more": false
}

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). 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 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: At Risk, 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: `At Risk`, `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. 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

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

Get Profile

Import Wallets

​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