FOMO Family API: REST and WebSocket Guide

The FOMO Family API is an independent REST and WebSocket data service for developers building with fomo.family trader data. It resolves a FOMO handle to available Solana and EVM wallets, returns FOMO-reported PnL and available trade history, and exposes balances, leaderboards, written theses, and realtime activity through one API key.

It is unofficial and independent. It is not affiliated with, endorsed by, or sponsored by fomo.family.

If you want to make a first request immediately, create a key in the dashboard, keep it on your server, and call the leaderboard:

curl "https://api.fomoapi.io/v2/leaderboard/24h?limit=5" \
  -H "authorization: Bearer YOUR_API_KEY"

The developer reference and OpenAPI specification are the source of truth for current response fields, access rules, and credit costs.

Is there an official fomo.family API?

fomo.family does not currently publish a documented developer API, public API-key flow, or official SDK. The app has its own private application interfaces, but a private interface used by a website is not the same thing as a supported public API contract.

FOMO API fills the developer-use case as a separate service. It normalizes the available social-trading and wallet data behind stable REST routes and documents the limitations of each response. That distinction matters:

Use fomo.family when you want the trading application. Use FOMO API when your own server, bot, dashboard, or research workflow needs structured data.

What data can the API return?

The useful starting routes are:

This page is an overview, not a substitute for the live schema. Check the API docs before persisting fields or calculating request costs.

Resolve a FOMO handle to wallets

Most integrations begin with a handle because that is the identity a person knows. Encode the handle, send your key in the Authorization header, and request the profile:

curl "https://api.fomoapi.io/v2/users/EXAMPLE_HANDLE" \
  -H "authorization: Bearer YOUR_API_KEY"

The response can include the normalized profile, FOMO-reported performance windows, and resolved Solana and EVM wallets. Do not substitute a different address when a wallet is absent or marked as resolving. The correct behavior is to show that state and retry later according to your product's policy.

Wallet resolution is valuable because it lets an application connect a social identity to public-chain activity. It does not make every upstream metric independently verified: the API passes through FOMO-reported PnL and labels it as such.

For typed code, error handling, and narrow response types, use the FOMO API TypeScript quickstart.

Request trades and balances

Use the canonical per-handle trade route rather than older examples that place a user in a query parameter:

curl "https://api.fomoapi.io/v2/users/EXAMPLE_HANDLE/positions?limit=25" \
  -H "authorization: Bearer YOUR_API_KEY"

curl "https://api.fomoapi.io/v2/users/EXAMPLE_HANDLE/balances" \
  -H "authorization: Bearer YOUR_API_KEY"

Trade responses describe the history currently available from FOMO. They do not promise an exhaustive lifetime ledger. Read response coverage fields where present, and resolve the wallets first if your application must independently reconstruct complete chain history.

Balances answer a different question: what positions are visible now. Do not combine a point-in-time balance and a trade-history response as though both were captured in one atomic snapshot.

Query leaderboards and theses

The leaderboard accepts 24h, 7d, 30d, or all as the window:

curl "https://api.fomoapi.io/v2/leaderboard/7d?limit=20" \
  -H "authorization: Bearer YOUR_API_KEY"

Treat rankings as observations that can change between requests. A leaderboard can help discover traders, but it is not financial advice and does not establish that past performance will continue.

Thesis routes expose the written context traders attach to positions:

GET /v2/thesis/token/{mint}
GET /v2/thesis/user/{id}

Theses are user-authored opinions. They can be useful inputs for narrative research, but applications should display their author and time rather than present them as verified facts.

Connect to the FOMO Family WebSocket

There are two separate streams:

• wss://api.fomoapi.io/ws/alerts carries app-feed activity. Current delay and access rules depend on the key's plan and trial state.
• wss://api.fomoapi.io/ws/trades carries the separate on-chain trade stream and requires Growth or Scale access.

A minimal Node client for the app-activity stream looks like this:

import WebSocket from "ws";

const key = process.env.FOMO_API_KEY;
if (!key) throw new Error("FOMO_API_KEY is required");

const socket = new WebSocket(
  `wss://api.fomoapi.io/ws/alerts?key=${encodeURIComponent(key)}`,
);

socket.on("message", raw => {
  const event = JSON.parse(raw.toString());
  if (event.type === "alert") console.log(event);
});

socket.on("error", error => console.error("FOMO stream error", error));

Production clients also need bounded reconnects, heartbeat monitoring, duplicate handling, and downstream backpressure. The production WebSocket guide implements those pieces and explains recovery after a disconnect.

Authentication, credits, and safe key handling

Send the key as authorization: Bearer YOUR_API_KEY for data routes. Keep it in a server-side secret rather than embedding it in shipped browser JavaScript or a public repository.

Authenticated responses can include credit-cost and remaining-credit headers. Endpoint costs and plan allowances can change, so use the current pricing page and API reference instead of copying an old number into application logic.

A production integration should also:

1. validate the response fields it persists;
2. distinguish authentication, credit, not-found, rate-limit, and upstream failures;
3. retry only errors documented as transient;
4. log route, status, duration, and credit headers without logging the key;
5. cache or coalesce repeated reads when the product does not require a fresh request.

What can you build with it?

Common uses include trader-research dashboards, wallet watchlists, PnL leaderboards, thesis and narrative monitors, Telegram or Discord alerts, and data inputs for independently operated agents. The API supplies data; trading authorization and transaction execution remain separate responsibilities for the application developer.

Start with one concrete task. Resolve a handle, inspect the returned coverage and wallets, then add trades or a stream only when the product needs them. That produces a smaller, easier-to-audit integration than consuming every endpoint at once.

Start with a verified request

1. Create an API key in the dashboard.
2. Copy the leaderboard request at the top of this guide.
3. Confirm the HTTP status and credit headers before trusting the JSON.
4. Open the API docs for the current schema.
5. Move to the TypeScript quickstart when you are ready to build a typed client.

That is the shortest supported path from a search for a FOMO Family API to a working, documented request.