> ## Documentation Index > Fetch the complete documentation index at: https://docs.formo.so/llms.txt > Use this file to discover all available pages before exploring further. # Search wallet profiles ## OpenAPI ````yaml /api/openapi.json get /v0/profiles openapi: 3.1.0 info: title: Formo Public API description: >- REST API for managing Formo projects, analytics, alerts, boards, charts, contracts, segments, and AI chat. **Auth.** All endpoints require a workspace API key with the appropriate scopes (see `x-api-scopes`). **Response shape.** Successful responses return the resource directly (or `{ data: [...], total, page, size, has_more }` for paginated lists). HTTP status carries success/failure; there is no envelope wrapping success bodies. **Errors.** Every non-2xx response uses the `Error` envelope: `{ error: { code, message, doc_url, param?, details? } }`. Branch on the machine-readable `code` (see `ErrorCode` enum) and follow `doc_url` to the matching section of the [errors reference](https://docs.formo.so/api/errors). **Idempotency.** Pass an `Idempotency-Key` header on POST/PUT/PATCH/DELETE to make retries safe; the response is cached for 24 h and replayed on duplicate keys. version: 0.1.0 contact: name: Formo url: https://formo.so servers: - url: https://api.formo.so description: API Server (boards, alerts, contracts, segments, profiles, query, import) - url: https://events.formo.so description: Events Server (event ingestion) security: - WorkspaceApiKey: [] tags: - name: Alerts description: Manage project alerts and notifications - name: Boards description: Manage dashboard boards - name: Charts description: Manage charts within boards - name: Contracts description: Manage blockchain contract monitoring - name: Segments description: Manage user segments - name: Profiles description: Wallet profiles and import - name: Query description: >- Execute SQL queries and call pre-built analytics endpoints (KPIs, top pages, lifecycle, retention, revenue). Requires the query:read scope. - name: Events description: Event ingestion API (events.formo.so) paths: /v0/profiles: get: tags: - Profiles summary: Search wallet profiles operationId: searchProfiles parameters: - name: address in: query schema: type: string description: >- 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. - name: expand in: query schema: type: string description: 'Comma-separated: apps, chains, tokens, labels' - name: order_by in: query schema: type: string enum: - net_worth_usd - tx_count - first_onchain - last_onchain - updated_at - first_seen - last_seen - num_sessions - revenue - volume - points description: Sort field - name: order_dir in: query schema: type: string enum: - asc - desc description: Sort direction - name: page in: query schema: type: integer minimum: 1 default: 1 description: 1-indexed page number (default 1). - name: size in: query schema: type: integer default: 100 minimum: 1 maximum: 1000 description: Page size (default 100, max 1000). requestBody: required: false description: Optional filter conditions content: application/json: schema: $ref: '#/components/schemas/ProfileFilter' examples: highNetWorth: summary: Users with >$10k net worth value: conditions: - field: users.net_worth_usd op: gt value: 10000 logic: and chainFilter: summary: Users active on Ethereum with >$1k balance value: conditions: - field: chains.1.balance op: gt value: 1000 logic: and labelFilter: summary: Coinbase verified users value: conditions: - field: labels.coinbase.verified_account op: eq value: 'true' logic: and tokenFilter: summary: Users holding USDC in any protocol value: conditions: - field: >- tokens.0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48.balance op: gt value: 0 scope: any logic: and responses: '200': description: Paginated wallet profile search results. content: application/json: schema: allOf: - $ref: '#/components/schemas/PaginatedListMeta' - type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/Profile' example: data: - address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' net_worth_usd: 12345.67 page: 1 size: 100 total: 1 has_more: false '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' components: schemas: ProfileFilter: type: object description: Filter conditions for profile search properties: conditions: type: array items: $ref: '#/components/schemas/FilterCondition' logic: type: string enum: - and - or default: and PaginatedListMeta: type: object description: >- 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. required: - page - size - total - has_more properties: page: type: integer description: 1-indexed page number echoed from the request. size: type: integer description: Page size echoed from the request. total: type: integer description: Total row count across all pages. has_more: type: boolean description: True when more pages remain (`page * size < total`). Profile: type: object description: Comprehensive wallet profile with onchain and offchain data properties: address: type: string net_worth_usd: type: number tx_count: type: integer first_onchain: type: string description: First onchain activity date last_onchain: type: string description: Last onchain activity date updated_at: type: string format: date-time ens: type: string nullable: true farcaster: type: string nullable: true lens: type: string nullable: true basenames: type: string nullable: true linea: type: string nullable: true avatar: type: string nullable: true display_name: type: string nullable: true description: type: string nullable: true discord: type: string nullable: true telegram: type: string nullable: true twitter: type: string nullable: true github: type: string nullable: true linkedin: type: string nullable: true email: type: string nullable: true instagram: type: string nullable: true facebook: type: string nullable: true website: type: string nullable: true reddit: type: string nullable: true youtube: type: string nullable: true tiktok: type: string nullable: true first_seen: type: string nullable: true description: First seen in project last_seen: type: string nullable: true description: Last seen in project lifecycle: type: string nullable: true enum: - New - Returning - Power user - Resurrected - At Risk - Churned num_sessions: type: integer nullable: true revenue: type: number nullable: true volume: type: number nullable: true points: type: number nullable: true device: type: string nullable: true browser: type: string nullable: true os: type: string nullable: true location: type: string nullable: true first_utm_source: type: string nullable: true first_utm_medium: type: string nullable: true first_utm_campaign: type: string nullable: true first_referrer: type: string nullable: true last_utm_source: type: string nullable: true last_utm_medium: type: string nullable: true last_utm_campaign: type: string nullable: true last_referrer: type: string nullable: true first_referrer_url: type: string nullable: true description: First referrer full URL last_referrer_url: type: string nullable: true description: Last referrer full URL first_ref: type: string nullable: true description: First referral code last_ref: type: string nullable: true description: Last referral code first_utm_content: type: string nullable: true description: First UTM content last_utm_content: type: string nullable: true description: Last UTM content first_utm_term: type: string nullable: true description: First UTM term last_utm_term: type: string nullable: true description: Last UTM term last_type: type: string nullable: true description: Last event type last_event: type: string nullable: true description: Last event name last_properties: type: string nullable: true description: Last event properties (JSON string) activity_dates: type: array items: type: string format: date nullable: true description: Array of activity dates (YYYY-MM-DD format) chains: type: array items: $ref: '#/components/schemas/WalletChain' description: Requires expand=chains apps: type: array items: $ref: '#/components/schemas/WalletApp' description: Requires expand=apps tokens: type: array items: $ref: '#/components/schemas/WalletToken' description: Requires expand=tokens labels: type: array items: $ref: '#/components/schemas/WalletLabel' description: Requires expand=labels FilterCondition: type: object required: - field - op - value properties: field: type: string description: >- Field path. Profile: users.net_worth_usd, users.volume, users.revenue, users.points. Engagement: users.device, users.browser, users.os, users.location. Lifecycle: users.lifecycle. Socials: users.ens, users.farcaster, etc. Chains: chains.balance, chains.{chain_id}.balance. Apps: apps.{app_id}.balance. Tokens: tokens.{address}.balance. Labels: labels.{tag_id} op: type: string enum: - eq - neq - gt - gte - lt - lte - in - nin value: description: Filter value (string, number, boolean, or array) scope: type: string enum: - any - protocol description: 'For token filters: any=wallet+protocol, protocol=specific app' appId: type: string description: For token scope=protocol (e.g. aave-v3) WalletChain: type: object properties: chain_id: type: string net_worth_usd: type: number tx_count: type: integer first_onchain: type: string last_onchain: type: string WalletApp: type: object properties: chain_id: type: string id: type: string name: type: string img: type: string nullable: true url: type: string nullable: true balance_usd: type: number WalletToken: type: object properties: chain_id: type: string token_address: type: string app_id: type: string name: type: string symbol: type: string img: type: string nullable: true decimals: type: integer price: type: number balance: type: string balance_usd: type: number WalletLabel: type: object properties: id: type: string description: e.g. coinbase.verified_account value: type: string chain_id: type: string source: type: string Error: type: object description: >- Standard error envelope returned by every public API endpoint for any non-2xx response. The HTTP status code carries success/failure; the body provides a machine-readable `code`, a human-readable `message`, and a `doc_url` pointing at the matching section of the docs so agents can fetch context on the fly. properties: error: type: object required: - code - message - doc_url properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string description: >- Human-readable error description. Wording may change between releases, so branch on `code`, not `message`. doc_url: type: string format: uri description: >- Link to the matching section of the errors reference at https://docs.formo.so/api/errors. param: type: string description: >- When the error pertains to a specific request field, the dotted path to that field (e.g. `body.trigger_filters.0.value`). details: type: object additionalProperties: true description: >- Code-specific extra context. For `INVALID_VALIDATION_REQUEST` this is a `{ fieldPath: message }` map of every Zod validation failure. required: - error ErrorCode: type: string description: >- Stable, enumerated error codes. New codes may be added in any release; clients should treat unknown codes as the closest matching HTTP status family. enum: - INTERNAL_SERVER_ERROR - INVALID_VALIDATION_REQUEST - UNAUTHORIZED - BAD_REQUEST - FORBIDDEN - NOT_FOUND - CONFLICT - INVALID_CHAIN_ID - CONTEXT_LIMIT_EXCEEDED - SERVICE_UNAVAILABLE - TOO_MANY_REQUESTS - IDEMPOTENCY_IN_PROGRESS - INVALID_IDEMPOTENCY_KEY responses: BadRequest: description: >- The request was rejected. `code` is either `INVALID_VALIDATION_REQUEST` (Zod schema mismatch; `details` carries a `{ fieldPath: message }` map) or `BAD_REQUEST` (semantic validation failure outside Zod, e.g. mismatched IDs, business-rule violations). Branch on `code`, not status, to tell the two apart. content: application/json: schema: $ref: '#/components/schemas/Error' examples: validation: summary: Zod schema mismatch value: error: code: INVALID_VALIDATION_REQUEST message: Invalid request data doc_url: https://docs.formo.so/api/errors#invalid_validation_request details: body.name: String must contain at least 1 character(s) semantic: summary: Semantic validation failure value: error: code: BAD_REQUEST message: Target board must be different from the current board doc_url: https://docs.formo.so/api/errors#bad_request Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHORIZED message: Invalid API key doc_url: https://docs.formo.so/api/errors#unauthorized Forbidden: description: The API key is valid but lacks the required scope for this endpoint. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: FORBIDDEN message: 'API key missing required scope: alerts:write' doc_url: https://docs.formo.so/api/errors#forbidden TooManyRequests: description: >- Per-workspace rate limit exceeded. Inspect the `RateLimit-*` response headers and back off. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: TOO_MANY_REQUESTS message: Too many requests doc_url: https://docs.formo.so/api/errors#too_many_requests InternalServerError: description: >- An unexpected error occurred on the server. The error has been logged; retry with exponential backoff. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INTERNAL_SERVER_ERROR message: Internal Server Error doc_url: https://docs.formo.so/api/errors#internal_server_error securitySchemes: WorkspaceApiKey: type: http scheme: bearer description: >- Workspace API key (e.g. `formo_xxx`). Create one in the Formo dashboard under Team Settings > API Keys. ````