Profiles - Formo Docs

The formo profiles command group lets you look up individual wallet profiles, search your user base, merge-update identity properties, and manage labels.

Lifecycle Threshold Options

profiles get and profiles search accept optional lifecycle threshold overrides:

Option	Type	Description
`--new-window-days`	`number`	Override lifecycle new-user window in days
`--churn-window-days`	`number`	Override lifecycle churn window in days
`--power-user-min-active-days`	`number`	Override lifecycle power-user minimum active days
`--power-user-window-days`	`number`	Override lifecycle power-user window in days
`--resurrected-gap-days`	`number`	Override lifecycle resurrected gap in days
`--at-risk-min-days-inactive`	`number`	Override lifecycle at-risk minimum inactive days
`--at-risk-prior-active-days-threshold`	`number`	Override lifecycle at-risk prior active days threshold

`formo profiles get <address>`

Fetch a single wallet profile by address or ENS name.

Requires profiles:read scope on your API key.

Options

Option	Type	Required	Description
`--expand`	`string`	❌	Comma-separated fields to expand: `apps`, `chains`, `tokens`, `labels`

The lifecycle threshold options listed above are also supported.

Examples

formo profiles get 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
formo profiles get vitalik.eth --expand labels,chains
formo profiles get vitalik.eth --expand apps,chains,tokens,labels --churn-window-days 30

`formo profiles search`

Search wallet profiles with optional filters, sorting, free-text search, and pagination.

Requires profiles:read scope on your API key.

Options

Option	Type	Required	Description
`--address`	`string`	❌	Filter by wallet address
`--search`	`string`	❌	Free-text search across address and identity fields
`--page`	`number`	❌	Page number, 1-indexed
`--size`	`number`	❌	Page size
`--order-by`	`enum`	❌	Field to sort by
`--order-dir`	`enum`	❌	Sort direction: `asc` or `desc`
`--expand`	`string`	❌	Comma-separated fields to expand
`--conditions`	`string`	❌	JSON array of `FilterCondition` objects
`--logic`	`enum`	❌	Combine conditions with `and` or `or`

The lifecycle threshold options listed above are also supported.

`--order-by` Values

last_onchain, first_onchain, net_worth_usd, updated_at, tx_count, first_seen, last_seen, num_sessions, revenue, volume, points

Examples

# List first 10 profiles
formo profiles search --size 10

# Search text fields
formo profiles search --search vitalik --size 5

# Top 5 profiles by net worth
formo profiles search --order-by net_worth_usd --order-dir desc --size 5

# Search with a typed filter condition
formo profiles search \
  --conditions '[{"field":"users.net_worth_usd","op":"gt","value":10000}]' \
  --size 20

# Search profiles matching either condition
formo profiles search \
  --conditions '[{"field":"users.net_worth_usd","op":"gt","value":10000},{"field":"users.volume","op":"gt","value":1000}]' \
  --logic or \
  --size 20

# Filter by onchain balance on Ethereum
formo profiles search \
  --conditions '[{"field":"chains.1.balance","op":"gt","value":1000}]' \
  --size 20

The response is a paginated envelope: { data, total, page, size, has_more }.

Filter Conditions

--conditions accepts a JSON array of filter condition objects:

[
  { "field": "users.net_worth_usd", "op": "gt", "value": 10000 },
  { "field": "chains.1.balance", "op": "gte", "value": 1000 }
]

field must be a typed path such as users.net_worth_usd, chains.1.balance, apps.uniswap-v3.balance, tokens.0xA0b8...48.balance, or labels.vip. Bare names like net_worth_usd are rejected by the CLI because the API ignores them.

Filter Operators

eq, neq, gt, gte, lt, lte, in, nin

`formo profiles update <address>`

Merge-update identity properties on a single wallet profile.

Requires profiles:write scope on your API key.

Options

Option	Type	Required	Description
`--properties`	`string`	✅	JSON object of properties to merge

Allowed property keys: user_id, display_name, email, farcaster, discord, twitter, telegram, instagram, website, github, linkedin, facebook, tiktok, youtube, reddit, avatar, description, location, ens, lens, basenames, linea

formo profiles update 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 \
  --properties '{"display_name":"Vitalik","twitter":"VitalikButerin"}'

`formo profiles properties batch`

Batch update first-party profile properties for up to 100 wallets.

Requires profiles:write scope on your API key.

Options

Option	Type	Required	Description
`--rows`	`string`	✅	JSON array of flat `{address, ...properties}` objects

formo profiles properties batch \
  --rows '[{"address":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","display_name":"alice.eth","email":"alice@example.com"}]'

ENS names are not resolved in batch requests. Use wallet addresses in each address field.

`formo profiles labels create <address>`

Upsert one or more labels on a wallet profile. Provide either a single label with --tag-id or a wallet-local batch with --labels.

Requires profiles:write scope on your API key.

Options

Option	Type	Required	Description
`--tag-id`	`string`	❌	Label identifier, required unless `--labels` is provided
`--value`	`string`	❌	Optional label value
`--chain-id`	`string`	❌	Optional chain identifier the label applies to
`--timestamp`	`string`	❌	Optional historical ISO-8601 timestamp for the label row
`--is-deleted`	`boolean`	❌	Backfill a historical label removal tombstone
`--labels`	`string`	❌	JSON array of `UserLabelInput` objects for this wallet

Examples

formo profiles labels create 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --tag-id vip

formo profiles labels create 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 \
  --tag-id tier --value gold --chain-id 1

formo profiles labels create 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 \
  --tag-id tier --timestamp 2024-03-15T00:00:00.000Z --is-deleted

formo profiles labels create 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 \
  --labels '[{"tag_id":"vip"},{"tag_id":"airdrop_eligible","chain_id":"1"}]'

`formo profiles labels batch`

Batch upsert labels across up to 100 wallets.

Requires profiles:write scope on your API key.

Options

Option	Type	Required	Description
`--labels`	`string`	✅	JSON array of `{address, tag_id, value?, chain_id?, timestamp?, _is_deleted?}` objects

formo profiles labels batch \
  --labels '[{"address":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","tag_id":"vip","value":"tier-1"}]'

ENS names are not resolved in batch requests. Use wallet addresses in each address field.

`formo profiles labels delete <address>`

Delete a label from a wallet profile. Pass --chain-id to scope deletion to a chain-specific label.

Requires profiles:write scope on your API key.

Options

Option	Type	Required	Description
`--tag-id`	`string`	✅	Label identifier to delete
`--chain-id`	`string`	❌	Optional chain identifier to scope the deletion

formo profiles labels delete 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --tag-id vip

formo profiles labels delete 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 \
  --tag-id tier --chain-id 1

​Lifecycle Threshold Options

​formo profiles get <address>

​Options

​Examples

​formo profiles search

​Options

​--order-by Values

​Examples

​Filter Conditions

​Filter Operators

​formo profiles update <address>

​Options

​formo profiles properties batch

​Options

​formo profiles labels create <address>

​Options

​Examples

​formo profiles labels batch

​Options

​formo profiles labels delete <address>

​Options

Lifecycle Threshold Options

`formo profiles get <address>`

Options

Examples

`formo profiles search`

Options

`--order-by` Values

Examples

Filter Conditions

Filter Operators

`formo profiles update <address>`

Options

`formo profiles properties batch`

Options

`formo profiles labels create <address>`

Options

Examples

`formo profiles labels batch`

Options

`formo profiles labels delete <address>`

Options