> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fomoscan.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Live posts

> One socket for every new post, on every platform, filtered by platform and token.

![Frames on wss://stream.fomoscan.sh/v3 over time: FomoScan sends ready, you send subscribe, FomoScan confirms with subscribed, then sends posts; a ping from FomoScan is answered with a pong. Each socket costs 20,000 credits per started minute](https://mintcdn.com/socialscan/IovDmO5aKwtscGfq/images/art/v3-websocket.webp?fit=max\&auto=format\&n=IovDmO5aKwtscGfq\&q=85\&s=d107c58553722c55d6ab41db50f121e1)

`wss://stream.fomoscan.sh/v3` pushes every new post as we publish it, from every
platform, narrowed to the platforms and tokens you choose. A `post` frame carries
the envelope [`GET /v3/posts`](https://docs.fomoscan.sh/v3/guides/posts) returns, so one parser reads both.

> [!NOTE]
>
> The stream is included from the **Growth** plan. Keys on legacy plans keep the
> access they have. Other keys are refused on the handshake with
> `403 PLAN_REQUIRED`. The key needs the `basic` or `live:read` scope.
> [Which keys may connect](https://docs.fomoscan.sh/v3/websocket/frames.md#which-keys-may-connect) lists every rule.

## Connect

Send the key on the upgrade request, in `Authorization: Bearer <key>` or
`X-Api-Key: <key>`. The URL takes no key parameter.

```js theme={null}
import WebSocket from "ws";

const socket = new WebSocket("wss://stream.fomoscan.sh/v3", {
  headers: { Authorization: `Bearer ${process.env.FOMOSCAN_KEY}` },
});

socket.on("message", (raw) => {
  const frame = JSON.parse(raw.toString());
  if (frame.type === "ready") {
    socket.send(JSON.stringify({ type: "subscribe", topic: "posts" }));
  }
  if (frame.type === "post") console.log(frame.item.id, frame.cursor);
  if (frame.type === "error") console.error(frame.error);
});
```

```bash theme={null}
npx wscat -c "wss://stream.fomoscan.sh/v3" -H "Authorization: Bearer $FOMOSCAN_KEY"
```

> [!WARNING]
>
> A browser `WebSocket` cannot set headers. Hold the socket on your server and
> relay frames to your front end. Never ship the key to a browser.

## Subscribe

Nothing arrives before your first accepted `subscribe`:

```json theme={null}
{
  "type": "subscribe",
  "topic": "posts",
  "platforms": ["fomo", "pump"],
  "tokens": ["tok_solana_EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"],
  "since": "s_…"
}
```

| Field | Rule |
| - | - |
| `topic` | Required: `posts`. |
| `platforms` | Optional. Omit it for every platform. Posts come from `fomo` and `pump` today. |
| `tokens` | Optional. 1 to 50 token ids, `tok_<network>_<address>`. Omit it for every token. |
| `since` | Optional. The `cursor` of a frame you received. The stream first replays what you missed in the last 5 minutes. |

* A post must match both filters.
* A connection holds one subscription. A new `subscribe` replaces it in full,
  so send the whole token list each time.
* `{ "type": "unsubscribe" }` clears it. The socket stays open and keeps being
  charged.
* A rejected frame changes nothing and keeps the socket open.

## Price

Each open socket costs **20,000 credits per started minute**, from the same
balance as REST calls.

* The first minute is charged on connect, then one more every 60 seconds while
  the socket is open, with or without a subscription.
* One token, fifty tokens or every post cost the same. One socket carries every
  platform; each socket you open is charged on its own.
* A connect needs 20,000 credits left, or it gets `402 QUOTA_EXCEEDED`.

## Stay connected

The server pings every 30 seconds, and `ws` answers on its own. When neither a
ping nor a frame arrives for 75 seconds, terminate the socket and reconnect with
`since` set to the last `cursor` you handled.

> [card] [Frames and behaviour](https://docs.fomoscan.sh/v3/websocket/frames.md)
>
> Every server frame, error codes, replay, ordering, limits, close codes and a
> reconnect recipe.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.