### Search traders and tokens with GET /v2/search

Source: https://fomoapi.io/docs

Unified search over both traders and tokens. The first example searches for 'ansem' across all types; the second restricts to traders with 'ether'. Both return results with a 'type' field.

```bash
curl "https://api.fomoapi.io/v2/search?q=ansem"
```

```bash
curl "https://api.fomoapi.io/v2/search?q=ether&type=traders"
```

--------------------------------

### API Info Response

Source: https://fomoapi.io/docs

Example JSON response for the GET /v1 endpoint providing API metadata.

```json
{
  "name": "FOMO API",
  "version": "0.1.0",
  "tier": "free",
  "rateLimit": "60 requests / minute per IP",
  "dataset": { "source": "fomo", "traders": 12 },
  "endpoints": { … }
}
```

--------------------------------

### Trader resolution response example

Source: https://fomoapi.io/docs

Example JSON response from the trader resolution endpoint. Shows the structure including handle, PnL, volume, trades, followers, holdings, wallets, profile, and various flags. Note that some fields may be null if live data read fails.

```json
{
  "handle": "CryptoKaleo",
  "displayName": "K A L E O",
  "pnlUsd": 151383,
  "pnl": { "24h": 8231, "7d": 54120, "30d": 142900, "all": 151383 },
  "volumeUsd": 119165,
  "trades": 73,
  "followers": 19967,
  "holdings": 4,
  "wallets": {
    "solana": "5AhfPStn66hRYoNNDfJHSDgCH7fBbwMQZUECRrhTo62F",    "evm": "0x7b4d16237683fe1765e727eadf99c6f02adf0b59"  },
  "profile": {
    "followers": 19967,
    "averageHoldTimeSeconds": 63613,
    "fomoCreatedAt": "2025-09-03T23:25:33.441Z",    "accountAgeDays": 360  },
  "numTrades": 73,
  "swapCount": 184,
  "totalVolume": 119165.42,
  "following": 91,
  "averageHoldTimeSeconds": 63613,
  "createdAt": "2025-09-03T23:25:33.441Z",
  "accountAgeDays": 360,
  "description": "trader bio",
  "clan": { "id": "659b...", "name": "Ender", "icon": "...", "role": "member" },
  "activated": false, "private": false, "isRestricted": false, "isReferred": true,
  "verified": false
}
```

--------------------------------

### Example Notification Object

Source: https://fomoapi.io/docs

A sample JSON object representing a notification retrieved from the /v2/notifications endpoint.

```json
{
  "id": "alrt_1787..._42",
  "source": "push",
  "alertType": "price",
  "notificationType": "PRICE_ALERT",
  "trader": null,
  "token": "PONS",
  "tokenAddress": "0x39dbed3a...",
  "chainId": 4663,
  "chain": "robinhood",
  "usdValue": null,
  "text": "PONS is up 40% in the last hour",
  "ts": 1787876441738
}
```

--------------------------------

### Leaderboard Response

Source: https://fomoapi.io/docs

Example JSON response for the leaderboard endpoint containing trader data.

```json
{
  "window": "24h",
  "source": "fomo",
  "capturedAt": "2026-08-25T18:04:00Z",
  "count": 2,
  "traders": [
    {
      "rank": 1,
      "handle": "CryptoKaleo",
      "displayName": "K A L E O",
      "pnlUsd": 151383,
      "volumeUsd": 119165,
      "trades": 73,
      "followers": 19967,
      "holdings": 4,
      "wallets": {
        "solana": "5AhfPStn66hRYoNNDfJHSDgCH7fBbwMQZUECRrhTo62F",
        "evm": "0x7b4d16237683fe1765e727eadf99c6f02adf0b59"
      },
      "topTokens": [ "0x7fe995", "0x51fb76" ],
      "verified": true
    }
  ]
}
```

--------------------------------

### Leaderboard Query with Limit

Source: https://fomoapi.io/docs

Example cURL request for the leaderboard endpoint with a limit query parameter.

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

--------------------------------

### GET /health

Source: https://fomoapi.io/docs

Liveness probe. Returns ok, the loaded trader count, and process uptime.

```APIDOC
## GET /health

### Description
Liveness probe. Returns ok, the loaded trader count, and process uptime.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **ok** (boolean) - Health status
- **traders** (int) - Loaded trader count
- **uptime** (number) - Process uptime in seconds

#### Response Example
{ "ok": true, "traders": 12, "uptime": 1834.2 }
```

--------------------------------

### GET /v1

Source: https://fomoapi.io/docs

Returns the API description, your tier, rate limit, dataset size, and the endpoint list. Handy for a health/status probe with metadata.

```APIDOC
## GET /v1

### Description
Returns the API description, your tier, rate limit, dataset size, and the endpoint list. Handy for a health/status probe with metadata.

### Method
GET

### Endpoint
/v1

### Response
#### Success Response (200)
- **name** (string) - API name
- **version** (string) - API version
- **tier** (string) - Your tier
- **rateLimit** (string) - Rate limit description
- **dataset** (object) - Dataset information
- **endpoints** (object) - Endpoint list

#### Response Example
{
  "name": "FOMO API",
  "version": "0.1.0",
  "tier": "free",
  "rateLimit": "60 requests / minute per IP",
  "dataset": { "source": "fomo", "traders": 12 },
  "endpoints": { ... }
}
```

--------------------------------

### GET /v2/users/{handle}/spotlight

Source: https://fomoapi.io/docs

Returns FOMO's curated picks of a trader's best trades and theses, including entry/exit prices and PnL. Costs 250 credits.

```APIDOC
## GET /v2/users/{handle}/spotlight

### Description
FOMO's own pick of a trader's best work. Returns bestTrades and bestTheses arrays with trade details and PnL.

### Method
GET

### Endpoint
/v2/users/{handle}/spotlight

### Parameters
#### Path Parameters
- **handle** (string) - Required - The trader's handle.

### Response
#### Success Response (200)
- **bestTrades** (array) - FOMO's picks of strongest positions.
- **bestTheses** (array) - Trades with most-liked written theses.
- **tradeId** (string) - Trade ID, pass to /v2/trades/{tradeId} or its /comments.
- **token** (object) - What was traded.
- **chain** (string) - Where it was traded.
- **avgEntryPrice** (number) - Average entry price.
- **avgExitPrice** (number) - Average exit price.
- **realizedPnlUsd** (number) - Closed PnL.
- **unrealizedPnlUsd** (number) - Open PnL.
- **thesis** (string) - Written thesis.
- **thesisLikes** (number) - Likes on the thesis.
- **openedAt** (string) - When the position opened.
- **closedAt** (string) - When the position closed; null if still open.

#### Response Example
{
  "bestTrades": [
    {
      "tradeId": "trade_123",
      "token": {
        "symbol": "ETH"
      },
      "chain": "ethereum",
      "avgEntryPrice": 2000,
      "avgExitPrice": 2500,
      "realizedPnlUsd": 500,
      "unrealizedPnlUsd": 0,
      "thesis": "Bullish on ETH",
      "thesisLikes": 10,
      "openedAt": "2023-01-01T00:00:00Z",
      "closedAt": "2023-01-02T00:00:00Z"
    }
  ],
  "bestTheses": []
}
```

--------------------------------

### Health Check Response

Source: https://fomoapi.io/docs

Example JSON response for the GET /health endpoint.

```json
{ "ok": true, "traders": 12, "uptime": 1834.2 }
```

--------------------------------

### GET /api

Source: https://fomoapi.io/docs

Discovery endpoint that provides API metadata. It is keyless and can be used to explore the API.

```APIDOC
## GET /api

### Description
Returns API metadata and discovery information. This endpoint is keyless.

### Method
GET

### Endpoint
/api

### Authentication
None (keyless)

### Response
#### Success Response (200)
Returns API metadata.

#### Response Example
{
  "name": "FOMO API",
  "version": "1.0"
}
```

--------------------------------

### GET /v2/users/{handle}

Source: https://fomoapi.io/docs

Resolves a trader handle to on-chain wallets and returns associated data. This endpoint requires a Bearer token and costs 2,500 credits.

```APIDOC
## GET /v2/users/{handle}

### Description
Resolves a trader handle to on-chain wallets and returns associated data. This endpoint requires authentication and costs 2,500 credits.

### Method
GET

### Endpoint
/v2/users/{handle}

### Authentication
Bearer token required

### Parameters
#### Path Parameters
- **handle** (string) - Required - The trader handle to resolve.

### Response
#### Success Response (200)
Returns wallet and trader information.

#### Response Example
{
  "handle": "example_trader",
  "wallets": [
    "0x..."
  ]
}
```

--------------------------------

### GET /v2/leaderboard/{window}

Source: https://fomoapi.io/docs

Ranked traders for a time window. Each row carries both on-chain wallets, PnL, volume, and holdings - the exact shape your app renders.

```APIDOC
## GET /v2/leaderboard/{window}

### Description
Ranked traders for a time window. Each row carries both on-chain wallets, PnL, volume, and holdings - the exact shape your app renders.

### Method
GET

### Endpoint
/v2/leaderboard/{window}

### Parameters
#### Path Parameters
- **window** (string) - Required - Ranking window. Values: 24h, 7d, 30d, all

#### Query Parameters
- **limit** (int) - Optional - Max rows. FOMO caps the board at 150 (100 on all); defaults to the full set. Range: 1-150

### Request Example
curl https://api.fomoapi.io/v2/leaderboard/24h?limit=2 -H "authorization: Bearer YOUR_API_KEY"

### Response
#### Success Response (200)
- **window** (string) - The requested window
- **source** (string) - Data source
- **capturedAt** (string) - Timestamp of data capture
- **count** (int) - Number of traders returned
- **traders** (array) - List of trader objects
  - **rank** (int) - Position in this window
  - **handle** (string) - Social handle (use with /v2/users)
  - **displayName** (string) - Display name
  - **pnlUsd** (number) - Realized PnL in USD for the selected window
  - **volumeUsd** (number) - Trading volume in USD
  - **trades** (int) - Trade count
  - **followers** (int) - Follower count
  - **holdings** (int) - Number of tokens currently held
  - **wallets.solana** (string) - Solana wallet address
  - **wallets.evm** (string) - EVM wallet address
  - **topTokens** (string[]) - Top held token identifiers
  - **verified** (bool) - Verification flag exactly as fomo.family reports it; false when they report none

#### Response Example
{
  "window": "24h",
  "source": "fomo",
  "capturedAt": "2026-08-25T18:04:00Z",
  "count": 2,
  "traders": [
    {
      "rank": 1,
      "handle": "CryptoKaleo",
      "displayName": "K A L E O",
      "pnlUsd": 151383,
      "volumeUsd": 119165,
      "trades": 73,
      "followers": 19967,
      "holdings": 4,
      "wallets": {
        "solana": "5AhfPStn66hRYoNNDfJHSDgCH7fBbwMQZUECRrhTo62F",
        "evm": "0x7b4d16237683fe1765e727eadf99c6f02adf0b59"
      },
      "topTokens": [ "0x7fe995", "0x51fb76" ],
      "verified": true
    }
  ]
}
```

--------------------------------

### GET /v1

Source: https://fomoapi.io/docs

Discovery endpoint that returns a self-describing catalog of the API. It is keyless and can be used to explore available endpoints.

```APIDOC
## GET /v1

### Description
Returns a self-describing catalog of the API. This endpoint is keyless and can be used for discovery.

### Method
GET

### Endpoint
/v1

### Authentication
None (keyless)

### Response
#### Success Response (200)
Returns a catalog of available endpoints and metadata.

#### Response Example
{
  "endpoints": [
    {
      "path": "/v1",
      "method": "GET",
      "description": "API catalog"
    }
  ]
}
```

--------------------------------

### GET /ws/alerts

Source: https://fomoapi.io/docs

WebSocket stream for real-time alerts. Available with a free key for 7 days realtime, then delayed 15 seconds. Requires authentication.

```APIDOC
## GET /ws/alerts

### Description
WebSocket stream for real-time alerts. Requires authentication. Free keys get realtime for 7 days, then delayed 15 seconds.

### Method
GET (WebSocket upgrade)

### Endpoint
/ws/alerts

### Authentication
Bearer token required

### Response
#### Success Response (101)
WebSocket connection established.

#### Response Example
{
  "type": "alert",
  "data": {}
}
```

--------------------------------

### GET /v2/users/id/{userId}

Source: https://fomoapi.io/docs

Resolves a userId to a user profile, including wallets. Costs 2,500 credits and counts against the monthly wallet-resolution allowance.

```APIDOC
## GET /v2/users/id/{userId}

### Description
The inverse of /v2/users/{handle}. Returns the same identity payload as the handle route, including wallets.

### Method
GET

### Endpoint
/v2/users/id/{userId}

### Parameters
#### Path Parameters
- **userId** (string) - Required - The user's ID.

### Response
#### Success Response (200)
- **handle** (string) - The user's handle.
- **displayName** (string) - The user's display name.
- **wallets** (array) - The user's wallet addresses.
- (Other identity fields as in /v2/users/{handle})

#### Response Example
{
  "handle": "example_handle",
  "displayName": "Example",
  "wallets": [
    "0x123..."
  ]
}
```

--------------------------------

### GET /v2/alerts

Source: https://fomoapi.io/docs

Returns alerts feed data. This endpoint requires a Bearer token and costs 125 credits per call.

```APIDOC
## GET /v2/alerts

### Description
Returns alerts feed data. This endpoint requires authentication and costs 125 credits.

### Method
GET

### Endpoint
/v2/alerts

### Authentication
Bearer token required

### Response
#### Success Response (200)
Returns a list of alerts.

#### Response Example
{
  "alerts": [
    {
      "type": "trade",
      "data": {}
    }
  ]
}
```

--------------------------------

### Fetch token holders via GET /token/{address}/holders

Source: https://fomoapi.io/docs

Retrieves a list of tracked smart-money traders holding a specific token. Requires an authorization header with a valid API key.

```bash
$ curl https://api.fomoapi.io/token/So111...112/holders \
    -H "authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### GET /v2/users/{handle}

Source: https://fomoapi.io/docs

Resolves a single trader handle to comprehensive trader information, including live counts and flags. The handle is case-insensitive and a leading @ is allowed.

```APIDOC
## GET /v2/users/{handle}

### Description
Resolves a single trader handle to comprehensive trader information, including live counts and flags. The handle is case-insensitive and a leading @ is allowed.

### Method
GET

### Endpoint
/v2/users/{handle}

### Parameters
#### Path Parameters
- **handle** (string) - Required - The trader's handle, case-insensitive, leading @ allowed.

### Request Example
```curl https://api.fomoapi.io/v2/users/CryptoKaleo \
    -H "authorization: Bearer YOUR_API_KEY"
```
t
### Response
#### Success Response (200)
- **handle** (string) - The trader's handle.
- **displayName** (string) - Display name.
- **pnlUsd** (number) - Profit and loss in USD.
- **pnl** (object) - PnL breakdown: 24h, 7d, 30d, all.
- **volumeUsd** (number) - Total volume in USD.
- **trades** (integer) - Number of trades.
- **followers** (integer) - Number of followers.
- **holdings** (integer) - Number of holdings.
- **wallets** (object) - Wallet addresses: solana, evm.
- **profile** (object) - Profile details: followers, averageHoldTimeSeconds, fomoCreatedAt, accountAgeDays.
- **numTrades** (integer) - Number of trades.
- **swapCount** (integer) - Number of swaps.
- **totalVolume** (number) - Total volume in USD.
- **following** (integer) - Number of following.
- **averageHoldTimeSeconds** (integer) - Average hold time in seconds.
- **createdAt** (string) - Account creation timestamp.
- **accountAgeDays** (integer) - Account age in days.
- **description** (string) - Trader bio.
- **clan** (object) - Clan details: id, name, icon, role.
- **activated** (boolean) - Whether activated.
- **private** (boolean) - Whether private.
- **isRestricted** (boolean) - Whether restricted.
- **isReferred** (boolean) - Whether referred.
- **verified** (boolean) - Whether verified.
- **userId** (string) - User ID.
- **userHandle** (string) - User handle.
- **profilePictureLink** (string) - Profile picture URL.
- **coverPhotoLink** (string) - Cover photo URL.
- **thumbhash** (string) - Thumbhash.
- **topTokens[]** (array) - Top tokens.
- **friendsFollowing** (integer) - Number of friends following.
- **numFriendsFollowing** (integer) - Number of friends following.

#### Response Example
```
{
  "handle": "CryptoKaleo",
  "displayName": "K A L E O",
  "pnlUsd": 151383,
  "pnl": { "24h": 8231, "7d": 54120, "30d": 142900, "all": 151383 },
  "volumeUsd": 119165,
  "trades": 73,
  "followers": 19967,
  "holdings": 4,
  "wallets": {
    "solana": "5AhfPStn66hRYoNNDfJHSDgCH7fBbwMQZUECRrhTo62F",	n    "evm": "0x7b4d16237683fe1765e727eadf99c6f02adf0b59"	n  },
  "profile": {
    "followers": 19967,
    "averageHoldTimeSeconds": 63613,
    "fomoCreatedAt": "2025-09-03T23:25:33.441Z",	n    "accountAgeDays": 360
  },
  "numTrades": 73,
  "swapCount": 184,
  "totalVolume": 119165.42,
  "following": 91,
  "averageHoldTimeSeconds": 63613,
  "createdAt": "2025-09-03T23:25:33.441Z",
  "accountAgeDays": 360,
  "description": "trader bio",
  "clan": { "id": "659b...", "name": "Ender", "icon": "...", "role": "member" },
  "activated": false, "private": false, "isRestricted": false, "isReferred": true,
  "verified": false
}
```

### Error Handling
- **404** - Returns `{"error":"trader not found"}` if the handle isn't in the dataset.
```

--------------------------------

### Connect to on-chain trade stream with WebSocket

Source: https://fomoapi.io/docs

Opens a WebSocket to wss://api.fomoapi.io/ws/trades with an API key and chain filter. The example uses chain=robinhood and minUsd=500. Messages are parsed as JSON; trade messages with replay=true are ignored. The console logs side, token symbol, USD value, trader handle or wallet, and latency in milliseconds after the block.

```javascript
const url = "wss://api.fomoapi.io/ws/trades";
const ws = new WebSocket(url + "?key=YOUR_API_KEY&chain=robinhood&minUsd=500");
ws.onmessage = (e) => {
  const t = JSON.parse(e.data);
  if (t.type !== "trade" || t.replay) return;
  console.log(t.side, t.token.symbol, t.usdValue, t.trader.handle ?? t.trader.wallet, t.latencyMs + "ms after the block");
};
```

--------------------------------

### GET /v2/users/{handle}/following

Source: https://fomoapi.io/docs

Returns the list of traders that a given user follows, with live data. The endpoint is bounded at 300 names (or 200 due to FOMO's limit) and handles slow reads with partial results and retryable responses.

```APIDOC
## GET /v2/users/{handle}/following

### Description
Returns the list of traders that a given user follows, with live data. The endpoint is bounded at 300 names (or 200 due to FOMO's limit) and handles slow reads with partial results and retryable responses.

### Method
GET

### Endpoint
/v2/users/{handle}/following

### Parameters
#### Path Parameters
- **handle** (string) - Required - The handle of the trader whose following list is requested.

#### Query Parameters
- **limit** (number) - Optional - Returns fewer names than the default 300.

### Response
#### Success Response (200)
- **handle** (string) - The followed trader's handle.
- **displayName** (string) - The followed trader's display name.
- **followers** (number) - The followed trader's follower count.
- **following** (number) - The followed trader's following count.
- **trades** (number) - The followed trader's lifetime trade count.
- **swapCount** (number) - The followed trader's lifetime swap count.
- **volumeUsd** (number) - The followed trader's lifetime traded volume in USD.
- **pnl24h** (number) - The followed trader's 24h PnL in USD.
- **verified** (boolean) - Whether the followed trader is verified on FOMO.
- **private** (boolean) - Whether the followed trader's profile is private.
- **twitter** (string) - The followed trader's linked X profile, if any.
- **bio** (string) - The followed trader's profile description.
- **avatar** (string) - The followed trader's profile picture.
- **createdAt** (string) - The followed trader's FOMO signup time.
- **accountAgeDays** (number) - The followed trader's account age in days.
- **truncated** (boolean) - Top level: whether the list was cut (at our 300 bound or FOMO's 200 wall).
- **cap** (number) - Top level: our bound (300).
- **complete** (boolean) - Top level: true only when this is the trader's whole following list.
- **partial** (boolean) - Top level, only on a slow pull: we stopped early, ask again for the rest.
- **retryable** (boolean) - Top level, only on a slow pull: we stopped early, ask again for the rest.

#### Response Example
{
  "handle": "example_trader",
  "displayName": "Example Trader",
  "followers": 1234,
  "following": 56,
  "trades": 789,
  "swapCount": 101,
  "volumeUsd": 12345.67,
  "pnl24h": 89.01,
  "verified": true,
  "private": false,
  "twitter": "@example",
  "bio": "Example bio",
  "avatar": "https://example.com/avatar.png",
  "createdAt": "2023-01-01T00:00:00Z",
  "accountAgeDays": 365,
  "truncated": false,
  "cap": 300,
  "complete": true,
  "partial": false,
  "retryable": false
}

### Error Handling
- **404** - Handle not found by FOMO.
- **503** - Live read did not finish in time, with `retryable: true`.
- **402** - Out of credits.

### Credits
Flat 250 credits. No cost for 404 or failed reads.
```

--------------------------------

### GET /ws/trades

Source: https://fomoapi.io/docs

WebSocket stream for on-chain trades. Available on Growth and higher plans. Requires authentication.

```APIDOC
## GET /ws/trades

### Description
WebSocket stream for on-chain trades. Requires authentication and is available on Growth and higher plans.

### Method
GET (WebSocket upgrade)

### Endpoint
/ws/trades

### Authentication
Bearer token required

### Response
#### Success Response (101)
WebSocket connection established.

#### Response Example
{
  "type": "trade",
  "data": {}
}
```

--------------------------------

### Feed view alert message structure

Source: https://fomoapi.io/docs

Example JSON structure of an alert message received from the /ws/alerts stream.

```json
{
  "type": "alert",
  "alertType": "buy",           // buy | sell | thesis | whale | price | trade | ...
  "source": "feed",             // "feed" (activity feed) or "push" (mobile notification)
  "trader": "frankdegods",
  "token": "PONS",
  "tokenAddress": "0x39dbed3a...",
  "chainId": 4663,
  "chain": "robinhood",
  "usdValue": 4000,
  "text": "frankdegods bought $PONS ($4K size)",
  "ts": 1788378000000
}
```

--------------------------------

### Fetch Leaderboard via Python

Source: https://fomoapi.io/docs

Retrieve the 24-hour leaderboard using the requests library.

```python
import requests
r = requests.get(
    "https://api.fomoapi.io/v2/leaderboard/24h",
    headers={"authorization": "Bearer YOUR_API_KEY"},
)
print(r.json()["traders"])
```

--------------------------------

### GET /health

Source: https://fomoapi.io/docs

Health check endpoint that returns the API status. It is keyless and can be used to verify service availability.

```APIDOC
## GET /health

### Description
Returns the health status of the API. This endpoint is keyless and can be used for monitoring.

### Method
GET

### Endpoint
/health

### Authentication
None (keyless)

### Response
#### Success Response (200)
Returns a health status object.

#### Response Example
{
  "status": "ok"
}
```

--------------------------------

### GET /v2/search

Source: https://fomoapi.io/docs

Unified search over both traders and tokens in one call. Returns trader or token matches with a type field.

```APIDOC
## GET /v2/search

### Description
Performs a unified search over both traders and tokens. Trader matches return wallets, PnL, and stats; token matches return mint address, name, image, and market cap. Each result carries a `type` field.

### Method
GET

### Endpoint
/v2/search

### Parameters
#### Query Parameters
- **q** (string) - Required - Search query.
- **type** (string) - Optional - Restrict results: `traders`, `tokens`, or `all` (default).
- **limit** (integer) - Optional - Maximum number of results.

### Request Example
curl "https://api.fomoapi.io/v2/search?q=ansem"
curl "https://api.fomoapi.io/v2/search?q=ether&type=traders"

### Response
#### Success Response (200)
- **type** (string) - `trader` or `token`.
- For trader: wallets, PnL, stats.
- For token: mint address, name, image, market cap.

#### Response Example
{
  "type": "trader",
  "wallets": [],
  "pnl": 0,
  "stats": {}
}
```

--------------------------------

### GET /v2/thesis

Source: https://fomoapi.io/docs

Retrieves recent theses across all coins, with sorting by equity or PnL and filtering by minimum equity or chain.

```APIDOC
## GET /v2/thesis

### Description
Returns recent theses across all coins. Each thesis carries a numeric `networkId` and a friendly `chain` name. Supports sorting by equity or PnL and filtering by minimum equity or chain.

### Method
GET

### Endpoint
/v2/thesis

### Parameters
#### Query Parameters
- **sort** (string) - Optional - Sort order: `recent`, `equity`, or `pnl`.
- **minEquity** (number) - Optional - Minimum equity (USD) to filter theses.
- **chain** (string) - Optional - Chain filter: `robinhood`, `solana`, `base`, `bsc`, `eth`, or a raw chain id.

### Response
#### Success Response (200)
- **networkId** (number) - Numeric network identifier.
- **chain** (string) - Friendly chain name.
- **text** (string) - The written thesis.
- **handle** (string) - Trader handle.
- **name** (string) - Trader display name.
- **userId** (string) - Trader id.
- **equity** (number) - The trader's position value (USD).
- **tradeUsd** (number) - Size of the trade (USD).
- **isDev** (bool) - Whether the author is the token dev.
- **replies** (number) - Replies on the thesis.
- **ts** (string) - Timestamp.

#### Response Example
{
  "networkId": 0,
  "chain": "string",
  "text": "string",
  "handle": "string",
  "name": "string",
  "userId": "string",
  "equity": 0,
  "tradeUsd": 0,
  "isDev": false,
  "replies": 0,
  "ts": "string"
}
```

--------------------------------

### GET /v2/users/{handle}/balances

Source: https://fomoapi.io/docs

Retrieves a trader's entire multi-chain portfolio in one call, including holdings across Robinhood Chain, Solana, Ethereum, Base, and BSC. Returns holdings, total value, per-chain breakdown, and optional portfolio-level PnL fields. Supports optional chain filter.

```APIDOC
## GET /v2/users/{handle}/balances

### Description
Retrieves a trader's entire multi-chain portfolio in one call, including holdings across Robinhood Chain, Solana, Ethereum, Base, and BSC. Returns holdings, total value, per-chain breakdown, and optional portfolio-level PnL fields. Supports optional chain filter.

### Method
GET

### Endpoint
/v2/users/{handle}/balances

### Parameters
#### Path Parameters
- **handle** (string) - Required - The trader's handle.

#### Query Parameters
- **chain** (string) - Optional - Filter to a single chain. Allowed values: robinhood, solana, base, bsc, eth.

### Response
#### Success Response (200)
- **holdings** (array) - List of holding objects.
- **token** (object) - Token object with symbol, address, and networkId.
- **chain** (string) - Friendly chain name: robinhood, solana, base, bsc, ethereum.
- **amount** (number) - Tokens held.
- **priceUsd** (number) - Unit price in USD.
- **valueUsd** (number) - Position value in USD.
- **change24h** (number) - 24h price move in percent.
- **totalValueUsd** (number) - Sum of all holdings across every chain.
- **byChain** (object) - Per-chain rollup, e.g., { robinhood: {holdings, valueUsd}, solana: {...} }.
- **otherPnl** (object) - Portfolio-level other PnL, when present.
- **livePerpPnl** (object) - Live perp PnL, when present.
- **hyperliquidPerps** (object) - Hyperliquid perp positions, when present.

#### Response Example
{
  "holdings": [
    {
      "token": { "symbol": "string", "address": "string", "networkId": 0 },
      "chain": "robinhood",
      "amount": 0,
      "priceUsd": 0,
      "valueUsd": 0,
      "change24h": 0
    }
  ],
  "totalValueUsd": 0,
  "byChain": {},
  "otherPnl": {},
  "livePerpPnl": {},
  "hyperliquidPerps": {}
}
```

--------------------------------

### GET /v2/tokens/search

Source: https://fomoapi.io/docs

Token-only search by symbol or name. Returns token details such as symbol, address, name, image, and market cap.

```APIDOC
## GET /v2/tokens/search

### Description
Performs a token-only search by symbol or name. Returns token details including symbol, address, name, image, and market cap.

### Method
GET

### Endpoint
/v2/tokens/search

### Parameters
#### Query Parameters
- **q** (string) - Required - Search query (symbol or name).
- **limit** (integer) - Optional - Maximum number of results.

### Response
#### Success Response (200)
- **symbol** (string) - Token symbol.
- **address** (string) - Token address.
- **name** (string) - Token name.
- **image** (string) - Token image URL.
- **marketCapUsd** (number) - Market cap in USD.

#### Response Example
{
  "symbol": "string",
  "address": "string",
  "name": "string",
  "image": "string",
  "marketCapUsd": 0
}
```

--------------------------------

### Connect to feed view stream

Source: https://fomoapi.io/docs

JavaScript implementation to connect to the FOMO alerts WebSocket and filter for buy or sell events.

```javascript
const ws = new WebSocket("wss://api.fomoapi.io/ws/alerts?key=YOUR_API_KEY");
ws.onmessage = (e) => {
  const m = JSON.parse(e.data);
  if (m.type === "alert" && (m.alertType === "buy" || m.alertType === "sell"))
    console.log(m.trader, m.alertType, m.token, m.usdValue, "on", m.chain);
};
```

--------------------------------

### GET /v2/thesis/user/{id}

Source: https://fomoapi.io/docs

Retrieves every thesis written by one trader, newest first. Can be filtered by token address or chain.

```APIDOC
## GET /v2/thesis/user/{id}

### Description
Returns every thesis written by one trader, newest first. The `{id}` can be a handle or a fomo userId. Optionally filter by token address or chain.

### Method
GET

### Endpoint
/v2/thesis/user/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Trader handle or fomo userId.

#### Query Parameters
- **token** (string) - Optional - Token address to filter theses about a single token.
- **chain** (string) - Optional - Chain filter (e.g., `robinhood`).
- **sort** (string) - Optional - Sort order: `likes` or `recent`.

### Response
#### Success Response (200)
- **text** (string) - The written thesis.
- **handle** (string) - Trader handle.
- **name** (string) - Trader display name.
- **userId** (string) - Trader id.
- **equity** (number) - The trader's position value (USD).
- **tradeUsd** (number) - Size of the trade (USD).
- **isDev** (bool) - Whether the author is the token dev.
- **likes** (number) - Likes on the thesis.
- **replies** (number) - Replies on the thesis.
- **ts** (string) - Timestamp.

#### Response Example
{
  "text": "string",
  "handle": "string",
  "name": "string",
  "userId": "string",
  "equity": 0,
  "tradeUsd": 0,
  "isDev": false,
  "likes": 0,
  "replies": 0,
  "ts": "string"
}
```

--------------------------------

### Fetch Leaderboard via cURL

Source: https://fomoapi.io/docs

Retrieve the 24-hour leaderboard using a cURL command with an authorization header.

```bash
$ curl https://api.fomoapi.io/v2/leaderboard/24h \
    -H "authorization: Bearer YOUR_API_KEY"
```