Skip to main content

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.

Formo

​
Events API

  • Send individual or batches of events via events.formo.so to Formo.
  • High-throughput streaming ingestion with an easy-to-use HTTP API.
  • Supports 1000 requests/s and 20MB/s.

​
Profiles API

You can use the Profiles API for real-time personalization. Once you fetch a profile, you can use them in your app for real-time personalization.
  • Fetch wallet profile properties including net worth and wallet labels
  • Segment and target users based on location, device, and referrer
  • Real-time activation API for personalized user experiences
Available on x402 on MPP.

​
Query API

  • Connect BI tools and SQL clients via BI integration.
  • Query and filter raw analytics events, materialized views, and metrics.
  • Return the activity feed / event stream for an anonymous visitor or wallet.
  • Export data periodically to your data warehouse.

​
Charts API

  • Create and manage custom dashboards and charts.
  • Add, update, and remove charts with SQL-based queries and visualization options (bar, line, pie, funnel, stacked, retention, and more).

​
Segments API

  • Create and manage user segments based on filter conditions.
  • Segment users by DeFi positions, net worth, transaction count, device, browser, lifetime volume, and other attributes.

​
Contracts API

  • Monitor blockchain smart contract events across all major chains.
  • Add contracts by chain ID, address, and ABI to get fully-decoded transaction and smart contract events.

​
Alerts API

  • Create, update, and manage project alerts programmatically.
  • Configure alert conditions and notification channels (email, Slack, webhook).

​
Response shape

Successful responses return the resource directly - there is no envelope, no isSuccess discriminator. HTTP status alone (200/201/204 vs 4xx/5xx) carries success. 
{
  "id": "alrt_…",
  "name": "Daily revenue drop",
  "trigger_type": "event",
  "status": "active",
  "created_at": "2026-04-12T09:32:18.000Z",
  "updated_at": "2026-04-25T14:01:55.000Z"
}
DELETE returns 204 No Content with an empty body - don’t try to parse JSON on those.

​
Pagination

List endpoints use a Stripe-style envelope only because they need pagination metadata: 
{
  "data": [
    { "id": "a" },
    { "id": "b" }
  ],
  "page": 1,
  "size": 50,
  "total": 173,
  "has_more": true
}
FieldMeaning
dataThe page of rows
totalTotal count across all pages
page1-indexed page number echoed from the request
sizePage size echoed from the request
has_moretrue if there are pages after the current one

​
Idempotency

Pass an Idempotency-Key header on POST/PUT/PATCH/DELETE so retries can’t double-create or double-charge. The first response is cached for 24 hours and replayed byte-for-byte on retry. 
POST /v0/alerts HTTP/1.1
Authorization: Bearer formo_…
Idempotency-Key: 8a3a2b1e-7c4d-4a5e-9c2f-1f8a3a2b1e9f
The header is opt-in. See Idempotency for the full contract, failure modes, and client patterns.

​
Errors

Every non-2xx response uses the same envelope: 
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Trigger filters must contain at least one entry",
    "doc_url": "https://docs.formo.so/api/errors#bad_request",
    "param": "body.trigger_filters"
  }
}
Branch on error.code (a stable enum), not message or HTTP status alone. The doc_url field anchors to the matching section of the Errors reference, so AI agents can fetch remediation context without escalating to a human. See Errors for the full list of codes.

​
Versioning

The public API is mounted under /v0/. We treat the path version as a major version; we will add /v1/ (rather than break /v0/) for incompatible changes. While under /v0/ the contract is settling - breaking changes can land before /v1/ ships, and we will announce them in the changelog. Within a version we may add new endpoints, new optional request fields, new response fields (clients should ignore unknown fields), and new error codes within an existing HTTP status family. We will not remove or rename existing endpoints/fields, change the HTTP status of an existing error condition, or repurpose an existing code value.

​
FAQ

LayerLimitWindow
API (except Profiles)1,000 requests15 minutes
Profiles API10,000 requests15 minutes
Workspace100 requests1 second
Yes. The Profiles API returns wallet profile data including holdings, net worth, lifecycle stage, and labels. It also returns your first-party data (if the user has visited your app) such as country, device, browser, OS, and more. You can use this to personalize your app experience based on a user’s onchain activity.
Yes. Formo provides BI tool integration via BI Read tokens that connect to the Formo data warehouse. You can connect Metabase, Grafana, and other SQL-based tools to query your analytics data.

​
Support

Live support

Chat with our support team

Email

Email our founder at yos@formo.so