Integrate

API reference

A REST API under /v1 plus a WebSocket stream. JSON is snake_case and serialised from the same read models the web app renders, so the API returns exactly the numbers you see in FomoQuant.

Authentication

Send your fq_live_ key as a bearer token (or in x-api-key). Every plan creates live keys; the plan sets the rate limit. Every object carries "dataset": "live" and "livemode": true. Create keys on the API page.

Shell

curl https://fomoquant.app/v1/quant/token/XYZ \
  -H "Authorization: Bearer fq_live_…"

/v1/health, /v1/models and /openapi.json are public (IP rate-limited). The full OpenAPI 3 document is at https://fomoquant.app/openapi.json.

Rate limits

Limits are per key per minute. Defaults by plan:

Plan	Requests / minute	Keys
Free	60	live
Pro	600	live
Team	2,000	live

Every response carries the current window:

Headers

RateLimit-Limit: 600
RateLimit-Remaining: 597
RateLimit-Reset: 41
RateLimit-Policy: 600;w=60
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 597
X-RateLimit-Reset: 1791633641
Retry-After: 41            (only on 429)
X-Request-Id: req_…

Errors

Errors use HTTP status codes and a stable JSON body. Never parse the message; switch on code.

JSON

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Token \"$NOPE\" was not found in the live dataset.",
    "request_id": "req_…"
  }
}

Code	Status	When
`VALIDATION`	400	A path, query or body parameter is invalid. details.issues lists each problem with its path.
`UNAUTHORIZED`	401	Missing, malformed, unknown or revoked API key.
`PLAN_REQUIRED`	402	The feature needs a higher plan (e.g. backtests, live keys).
`FORBIDDEN`	403	The key lacks the required scope.
`NOT_FOUND`	404	The object does not exist in this key's dataset.
`METHOD_NOT_ALLOWED`	405	Wrong HTTP method for the route (see the Allow header).
`LIMIT_REACHED`	409	A plan quota is used up (e.g. number of webhooks).
`CONFLICT`	409	The request conflicts with the current state.
`PAYLOAD_TOO_LARGE`	413	The request body is too large.
`RATE_LIMITED`	429	Per-key limit exceeded. Wait Retry-After seconds.
`INTERNAL`	500	Unexpected error. Retry; report the request id if it persists.
`UPSTREAM_UNAVAILABLE`	503	A dependency (database, provider) is unavailable.

Pagination

List endpoints return { object: "list", dataset, livemode, data, has_more, next_cursor } (plus total where cheap). Pass next_cursor back as cursor until has_more is false. Cursors are opaque and stable for the ordering of the request.

Objects & freshness

Every object has object (its type), dataset and livemode.
Quant objects carry model_versions and a freshness block: updated_at, fomo_last_event_at, market_last_at, lags, stale and human-readable stale_reasons such as “Fomo activity delayed · Last update: 12m ago”.
Values are identical to the app: serialisation only renames keys to snake_case — nothing is recomputed or rounded.
null = not available (with the reason in the score's confidence or a reason field), never zero.
Research responses (signals, backtests, event studies, analogs) include the disclaimer.

Example responses use illustrative values ($XYZ, example_rhea, a placeholder address) — not real tokens or authors; every field name and shape is exactly what the API returns. Long sections are collapsed as { … }.

GET/v1/quant/token/{token}

scope tokens:read

Latest point-in-time quant snapshot of a token.

Plain scores (null = insufficient data), score_details with drivers that sum to each score, confidence and model version, active signals, market, activity, divergence_state, the feature vector, analog summary, model_versions and freshness.

Parameters

Name	Description
`token`required path · string	Token reference: `$XYZ`, `XYZ`, `tk_…`, `<chain>:<address>` or `<address>`. Symbol collisions resolve to the most active token.

tokenpath · stringrequired
Token reference: $XYZ, XYZ, tk_…, <chain>:<address> or <address>. Symbol collisions resolve to the most active token.

curl "https://fomoquant.app/v1/quant/token/XYZ" \
  -H "Authorization: Bearer $FOMOQUANT_API_KEY"

GET/v1/quant/token/{token}/analogs

scope tokens:read

Historical setups most similar to the token's current snapshot (analog-v1.0).

Feature-vector distance over momentum, crowding, early quality, narrative velocity, price momentum, volume acceleration and liquidity. Only candidates whose 24h outcome resolved before the snapshot are used, and the same token within ±24h is excluded.

Parameters

Name	Description
`token`required path · string	Token reference: `$XYZ`, `XYZ`, `tk_…`, `<chain>:<address>` or `<address>`. Symbol collisions resolve to the most active token.
`k` query · integer 1–100	Maximum analogs returned, nearest first.Default `40`

tokenpath · stringrequired
Token reference: $XYZ, XYZ, tk_…, <chain>:<address> or <address>. Symbol collisions resolve to the most active token.
kquery · integer 1–100
Maximum analogs returned, nearest first.
Default 40

curl "https://fomoquant.app/v1/quant/token/XYZ/analogs?k=20" \
  -H "Authorization: Bearer $FOMOQUANT_API_KEY"

GET/v1/quant/tokens

scope tokens:read

Tokens with their current scores, cursor-paginated.

Parameters

Name	Description
`sort` query · rule field	Any rule field (score key or feature such as unique_authors_1h).Default `momentum`
`dir` query · asc \| desc	Sort direction.Default `desc`
`limit` query · integer 1–100	Page size.Default `25`
`cursor` query · string	Opaque cursor from the previous page's `next_cursor`.
`narrative` query · slug	Narrative slug, e.g. ai-agents.
`chain` query · enum	One of solana, robinhood, base, bnb, eth, arc.
`q` query · string ≤ 64	Symbol / name search.

sortquery · rule field
Any rule field (score key or feature such as unique_authors_1h).
Default momentum
dirquery · asc | desc
Sort direction.
Default desc
limitquery · integer 1–100
Page size.
Default 25
cursorquery · string
Opaque cursor from the previous page's next_cursor.
narrativequery · slug
Narrative slug, e.g. ai-agents.
chainquery · enum
One of solana, robinhood, base, bnb, eth, arc.
qquery · string ≤ 64
Symbol / name search.

curl "https://fomoquant.app/v1/quant/tokens?sort=momentum&limit=25" \
  -H "Authorization: Bearer $FOMOQUANT_API_KEY"

POST/v1/quant/scan

scope tokens:read

Run a scanner rule set against the latest snapshot of every token.

All rules must pass (AND); a null value never passes. Free plans see a 15-minute delayed scanner (delayed_minutes). Send rules, a preset (early-attention, broad-momentum, high-conviction, low-crowding, smart-cohort, cooling-fast, narrative-breakout), or both.

Parameters

Name	Description
`preset` body · string	Scanner preset id; combined with rules when both are sent.
`rules` body · { field, op, value }[] ≤ 12	Conditions. `op` is one of `>` `>=` `<` `<=`; pct fields are fractions (0.05 = 5%).
`sort` body · rule field	Sort field (defaults to the preset's).
`sort_dir` body · asc \| desc	Sort direction.
`limit` body · integer 1–200	Rows returned.
`chains` body · chain[]	Restrict to chains.
`narrative` body · slug	Restrict to one narrative.

presetbody · string
Scanner preset id; combined with rules when both are sent.
rulesbody · { field, op, value }[] ≤ 12
Conditions. op is one of > >= < <=; pct fields are fractions (0.05 = 5%).
sortbody · rule field
Sort field (defaults to the preset's).
sort_dirbody · asc | desc
Sort direction.
limitbody · integer 1–200
Rows returned.
chainsbody · chain[]
Restrict to chains.
narrativebody · slug
Restrict to one narrative.

curl -X POST "https://fomoquant.app/v1/quant/scan" \
  -H "Authorization: Bearer $FOMOQUANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rules":[{"field":"momentum","op":">","value":75},{"field":"crowding","op":"<","value":30}],"limit":20}'

Signals

GET/v1/quant/signals
GET/v1/quant/signals/{id}

GET/v1/quant/signals

scope signals:read

The signal feed, newest first.

Parameters

Name	Description
`min_score` query · <score>:<value>	Minimum score at fire time, e.g. `momentum:70`. Scores: momentum, conviction, crowding, early_quality, narrative_velocity, divergence, smart_cohort.
`signal_type` query · csv	Comma-separated types, e.g. `EARLY_ACCELERATION,BROAD_ATTENTION`.
`chain` query · csv	Comma-separated chains.
`market_cap` query · number	Minimum market cap (USD).
`liquidity` query · number	Minimum liquidity (USD).
`created_after` query · ISO-8601 \| unix	Only signals fired after this time.
`status` query · active \| ended \| all	Lifecycle status.Default `all`
`token` query · token ref	Only signals on this token.
`limit` query · integer 1–100	Page size.Default `25`
`cursor` query · string	Opaque cursor from the previous page's `next_cursor`.

min_scorequery · <score>:<value>
Minimum score at fire time, e.g. momentum:70. Scores: momentum, conviction, crowding, early_quality, narrative_velocity, divergence, smart_cohort.
signal_typequery · csv
Comma-separated types, e.g. EARLY_ACCELERATION,BROAD_ATTENTION.
chainquery · csv
Comma-separated chains.
market_capquery · number
Minimum market cap (USD).
liquidityquery · number
Minimum liquidity (USD).
created_afterquery · ISO-8601 | unix
Only signals fired after this time.
statusquery · active | ended | all
Lifecycle status.
Default all
tokenquery · token ref
Only signals on this token.
limitquery · integer 1–100
Page size.
Default 25
cursorquery · string
Opaque cursor from the previous page's next_cursor.

curl "https://fomoquant.app/v1/quant/signals?signal_type=EARLY_ACCELERATION&min_score=momentum:60&status=active" \
  -H "Authorization: Bearer $FOMOQUANT_API_KEY"

GET/v1/quant/signals/{id}

scope signals:read

One signal with its conditions (threshold vs actual), feature snapshot at fire time, analog summary, prior firings and the rule's documentation.

Parameters

Name	Description
`id`required path · sig_…	Signal id.

idpath · sig_…required
Signal id.

curl "https://fomoquant.app/v1/quant/signals/sig_8d3k2m9q4x7v1c6b5n0t" \
  -H "Authorization: Bearer $FOMOQUANT_API_KEY"

Users

GET/v1/quant/users/{handle}

GET/v1/quant/users/{handle}

scope users:read

Point-in-time author metrics for a Fomo handle.

Hit rate with a Wilson interval, median lead time, false-positive rate, drawdown, consistency, outcome volatility, sector strength (only with ≥ 8 samples per sector) and a research score with confidence. Never follower-based.

Parameters

Name	Description
`handle`required path · string	Fomo handle with or without `@`.

handlepath · stringrequired
Fomo handle with or without @.

curl "https://fomoquant.app/v1/quant/users/example_rhea" \
  -H "Authorization: Bearer $FOMOQUANT_API_KEY"

Cohorts & narratives

GET/v1/quant/cohorts
GET/v1/quant/cohorts/{id}
GET/v1/quant/narratives
GET/v1/quant/narratives/rotation
GET/v1/quant/narratives/heatmap
GET/v1/quant/narratives/{slug}

GET/v1/quant/cohorts

scope cohorts:read

Algorithmic cohorts plus the cohorts you own (or share with your team).

Parameters

Name	Description
`kind` query · manual \| auto \| all	Filter by cohort kind.Default `all`

kindquery · manual | auto | all
Filter by cohort kind.
Default all

curl "https://fomoquant.app/v1/quant/cohorts?kind=auto" \
  -H "Authorization: Bearer $FOMOQUANT_API_KEY"

GET/v1/quant/cohorts/{id}

scope cohorts:read

Members, collective activity, tokens, active signals and convergence events.

Parameters

Name	Description
`id`required path · cohort_…	Cohort id.

idpath · cohort_…required
Cohort id.

curl "https://fomoquant.app/v1/quant/cohorts/cohort_h3k8m2q9x4v7c1d6b5n0" \
  -H "Authorization: Bearer $FOMOQUANT_API_KEY"

GET/v1/quant/narratives

scope narratives:read

Narrative map: attention share, 24h growth, authors, top tokens and top contributors.

curl "https://fomoquant.app/v1/quant/narratives" \
  -H "Authorization: Bearer $FOMOQUANT_API_KEY"

GET/v1/quant/narratives/rotation

scope narratives:read

Attention-share change per narrative.

Parameters

Name	Description
`window` query · 24h \| 7d	Comparison window.Default `24h`

windowquery · 24h | 7d
Comparison window.
Default 24h

curl "https://fomoquant.app/v1/quant/narratives/rotation?window=24h" \
  -H "Authorization: Bearer $FOMOQUANT_API_KEY"

GET/v1/quant/narratives/heatmap

scope narratives:read

Narrative × time matrix with raw values and per-row intensity (0–1).

Parameters

Name	Description
`metric` query · theses \| author_growth	Cell value.Default `theses`
`bucket` query · 1h \| 6h \| 1d	Column width.Default `1h`
`range` query · 48h \| 7d \| 30d	Time range.Default `48h`

metricquery · theses | author_growth
Cell value.
Default theses
bucketquery · 1h | 6h | 1d
Column width.
Default 1h
rangequery · 48h | 7d | 30d
Time range.
Default 48h

curl "https://fomoquant.app/v1/quant/narratives/heatmap?metric=theses&bucket=1h&range=48h" \
  -H "Authorization: Bearer $FOMOQUANT_API_KEY"

GET/v1/quant/narratives/{slug}

scope narratives:read

One narrative.

Parameters

Name	Description
`slug`required path · slug	Narrative slug, e.g. ai-agents.

slugpath · slugrequired
Narrative slug, e.g. ai-agents.

curl "https://fomoquant.app/v1/quant/narratives/ai-agents" \
  -H "Authorization: Bearer $FOMOQUANT_API_KEY"

Backtests & event studies

POST/v1/quant/backtests
GET/v1/quant/backtests/{id}
GET/v1/quant/event-studies
GET/v1/quant/event-studies/{slug}

POST/v1/quant/backtests

scope backtests:write

Queue a strict point-in-time backtest (Pro / Team).

Returns 202 with a queued run and a Location header; poll GET /v1/quant/backtests/{id} or use the SDK's backtests.wait. Without a plan that includes backtests the API answers 402 PLAN_REQUIRED.

Parameters

Name	Description
`rules`required body · { field, op, value }[] 1–12	Entry conditions (AND).
`horizon`required body · 15m \| 1h \| 6h \| 24h \| 3d \| 7d	Holding horizon.
`name` body · string ≤ 80	Label for the run.
`from` body · ISO-8601 \| unix	Start of the test window (default: all history).
`to` body · ISO-8601 \| unix	End of the test window.
`cooldown` body · horizon	Minimum spacing between two events of the same token. Default = horizon (non-overlapping samples).
`dead_token_policy` body · last_price \| total_loss \| exclude	How tokens that died inside the horizon are valued. Dead tokens are always included unless excluded explicitly (then counted and warned).Default `last_price`
`universe` body · { chains?, min_liquidity_usd? }	Restrict the universe.

rulesbody · { field, op, value }[] 1–12required
Entry conditions (AND).
horizonbody · 15m | 1h | 6h | 24h | 3d | 7drequired
Holding horizon.
namebody · string ≤ 80
Label for the run.
frombody · ISO-8601 | unix
Start of the test window (default: all history).
tobody · ISO-8601 | unix
End of the test window.
cooldownbody · horizon
Minimum spacing between two events of the same token. Default = horizon (non-overlapping samples).
dead_token_policybody · last_price | total_loss | exclude
How tokens that died inside the horizon are valued. Dead tokens are always included unless excluded explicitly (then counted and warned).
Default last_price
universebody · { chains?, min_liquidity_usd? }
Restrict the universe.

curl -X POST "https://fomoquant.app/v1/quant/backtests" \
  -H "Authorization: Bearer $FOMOQUANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rules":[{"field":"momentum","op":">","value":80},{"field":"early_quality","op":">","value":70},{"field":"crowding","op":"<","value":30}],"horizon":"24h"}'

GET/v1/quant/backtests/{id}

scope backtests:read

A backtest run — poll until status is done or failed.

Result: N, hit rate (+ Wilson CI), median, mean and 10% trimmed mean return, median max drawdown, median time to peak, best/worst, return and drawdown distributions, warnings, every event and the leakage checks.

Parameters

Name	Description
`id`required path · btr_…	Backtest run id.

idpath · btr_…required
Backtest run id.

curl "https://fomoquant.app/v1/quant/backtests/btr_6b5n0h3k8m2q9x4v7c1d" \
  -H "Authorization: Bearer $FOMOQUANT_API_KEY"

GET/v1/quant/event-studies

scope backtests:read

Event studies refreshed hourly over point-in-time history.

curl "https://fomoquant.app/v1/quant/event-studies" \
  -H "Authorization: Bearer $FOMOQUANT_API_KEY"

GET/v1/quant/event-studies/{slug}

scope backtests:read

One event study with per-horizon distributions.

Parameters

Name	Description
`slug`required path · slug	velocity-3x, hq-authors-converge, social-up-price-flat, crowding-spike, broad-attention or cooling.

slugpath · slugrequired
velocity-3x, hq-authors-converge, social-up-price-flat, crowding-spike, broad-attention or cooling.

curl "https://fomoquant.app/v1/quant/event-studies/velocity-3x" \
  -H "Authorization: Bearer $FOMOQUANT_API_KEY"

Webhooks

GET/v1/webhooks
POST/v1/webhooks
DELETE/v1/webhooks/{id}
POST/v1/webhooks/{id}/test

GET/v1/webhooks

scope webhooks:write

Webhooks registered for this key's dataset.

curl "https://fomoquant.app/v1/webhooks" \
  -H "Authorization: Bearer $FOMOQUANT_API_KEY"

POST/v1/webhooks

scope webhooks:write

Parameters

Name	Description
`url`required body · https URL	Receives signed POSTs. Private and loopback addresses are rejected.
`events`required body · event[]	Any of signal.created, token.score.updated, cohort.convergence.

urlbody · https URLrequired
Receives signed POSTs. Private and loopback addresses are rejected.
eventsbody · event[]required
Any of signal.created, token.score.updated, cohort.convergence.

curl -X POST "https://fomoquant.app/v1/webhooks" \
  -H "Authorization: Bearer $FOMOQUANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/fomoquant","events":["signal.created","token.score.updated"]}'

DELETE/v1/webhooks/{id}

scope webhooks:write

Delete a webhook.

Parameters

Name	Description
`id`required path · wh_…	Webhook id.

idpath · wh_…required
Webhook id.

curl -X DELETE "https://fomoquant.app/v1/webhooks/wh_1d6b5n0h3k8m2q9x4v7c" \
  -H "Authorization: Bearer $FOMOQUANT_API_KEY"

POST/v1/webhooks/{id}/test

scope webhooks:write

Send a signed webhook.test event now and report the endpoint's HTTP status. Never counts toward auto-disable.

Parameters

Name	Description
`id`required path · wh_…	Webhook id.

idpath · wh_…required
Webhook id.

curl -X POST "https://fomoquant.app/v1/webhooks/wh_1d6b5n0h3k8m2q9x4v7c/test" \
  -H "Authorization: Bearer $FOMOQUANT_API_KEY"

WebSocket stream

Scope stream:read. The WebSocket is served by a separate realtime host whose address can change: ask GET https://fomoquant.app/v1/stream/info for the current url (wss://…/v1/stream) before connecting, and again before reconnecting. While the host is offline it answers available: false with a human-readable message; REST endpoints and webhooks are unaffected. The SDK's stream() does this for you. Authenticate with the Authorization header, or ?key= where headers are impossible (browsers; use a key that has only the stream:read scope). You only receive events from your key's dataset.

Server → client

welcome (on connect)

{
  "type": "welcome",
  "connection_id": "conn_…",
  "request_id": "req_…",
  "dataset": "live",
  "livemode": true,
  "events": ["signal.created", "signal.ended", "score.updated", "cohort.convergence", "narrative.shift"],
  "limits": { "max_subscriptions": 20, "max_tokens_per_subscription": 100, "ping_interval_sec": 25 },
  "key": { "id": "key_…", "name": "Research notebook" }
}

Client → server

{ "type": "subscribe", "id": "my-ref-1", "events": ["signal.created", "score.updated"], "tokens": ["$XYZ"] }

// → { "type": "subscribed", "ref": "my-ref-1", "subscription_id": "sub_…", "events": [...], "tokens": ["$XYZ"] }
// unsubscribe: { "type": "unsubscribe", "subscription_id": "sub_…" }
// ping:        { "type": "ping" }  → { "type": "pong", "ts": "…" }

event

{
  "type": "event",
  "id": "ev_7c1d6b5n0h3k8m2q9x4v",
  "event": "signal.created",
  "created_at": "2026-10-10T11:54:00.000Z",
  "dataset": "live",
  "data": {
    "object": "signal",
    "dataset": "live",
    "livemode": true,
    "id": "sig_8d3k2m9q4x7v1c6b5n0t",
    "type": "EARLY_ACCELERATION",
    "label": "Early acceleration",
    "rule_version": "early_acceleration@1.0",
    "status": "active",
    "fired_at": "2026-10-10T11:54:00.000Z",
    "ended_at": null,
    "strength": 0.214,
    "scores": { … },
    "why": [
      "thesis velocity +218%",
      "unique authors +71% (12 authors this hour)",
      "crowding low (24)",
      …
    ],
    "analogs": {
      "n": 27,
      "median_24h": 0.168,
      "worst_drawdown_24h": -0.284,
      "positive_share": 0.59,
      "confidence": "MEDIUM"
    },
    "token": {
      "object": "token",
      "id": "tk_4f8k2m9q1x7c3v5b6n0d",
      "dataset": "live",
      "symbol": "XYZ",
      "name": "Xyzzy Agents",
      "chain": "base",
      "address": "0x1111111111111111111111111111111111111111",
      "logo_url": null,
      "status": "active",
      "narrative": { … },
      "fomo_url": null,
      "livemode": true
    }
  }
}

Events: signal.created, signal.ended, score.updated, cohort.convergence, narrative.shift. tokens filters apply to token-scoped events and accept $SYMBOL or tk_….
The server pings every 25 s (WebSocket ping + a {"type":"ping"} frame); unresponsive connections are closed.
Slow consumers receive {"type":"warning","code":"EVENTS_DROPPED"} instead of unbounded buffering — resync over REST.
Up to 20 subscriptions per connection, 10 connections per key and 30 client messages per 10 s. Revoking a key closes its sockets (code 4401); a plan change that no longer includes the key closes them with 4402.
Errors arrive as {"type":"error","code","message"} frames with the same codes as REST.

FomoQuant provides analytics and historical/statistical context, not financial advice or guaranteed predictions.

Authentication

Rate limits

Errors

Pagination

Objects & freshness

Tokens & scanner

Parameters

Parameters

Parameters

Parameters

Signals

Parameters

Parameters

Users

Parameters

Cohorts & narratives

Parameters

Parameters

Parameters

Parameters

Parameters

Backtests & event studies

Parameters

Parameters

Parameters

Webhooks

Parameters

Parameters

Parameters

Meta

WebSocket stream

Server → client

Client → server