API overview - Formo Docs

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 via x402 (formo.x402.paysponge.com) and MPP (formo.mpp.paysponge.com): pay per request, no API key required

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 a webhook notification channel (including Slack, via a Slack incoming-webhook URL).

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. For example, creating an alert returns the alert itself:

{
  "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
}

Field	Meaning
`data`	The page of rows
`total`	Total count across all pages
`page`	1-indexed page number echoed from the request
`size`	Page size echoed from the request
`has_more`	`true` if there are pages after the current one

Idempotency

Pass an Idempotency-Key header on POST/PUT/PATCH/DELETE requests to the Alerts, Charts, Contracts, Segments, and Import APIs 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

What are the rate limits for the Formo API?

Layer	Limit	Window
API (except Profiles)	1,000 requests	15 minutes
Profiles API	10,000 requests	15 minutes
Workspace	100 requests	1 second

​Events API

​Profiles API

​Query API

​Charts API

​Segments API

​Contracts API

​Alerts API

​Response shape

​Pagination

​Idempotency

​Errors

​Versioning

​FAQ