> For the complete documentation index, see [llms.txt](https://docs.surged.fun/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.surged.fun/integration/api/realtime.md).

# Realtime feed

One websocket carries new blocks, new launches, every trade and every phase change. Subscribe to what you care about; the server pushes and never asks.

```
wss://api.surged.fun/ws
```

## Subscribing

Send a JSON message naming the channels. You can subscribe and unsubscribe at any time.

```ts
const ws = new WebSocket('wss://api.surged.fun/ws')

ws.onopen = () => {
  ws.send(JSON.stringify({ subscribe: ['feed', 'blocks', `token:${token}`] }))
}
ws.onmessage = (event) => {
  const message = JSON.parse(event.data)
  // ...
}
```

The server replies `{ "type": "subscribed", "channels": [...] }` with everything you are on.

| Channel     | What arrives                                            |
| ----------- | ------------------------------------------------------- |
| `feed`      | Every launch and every trade, across all tokens.        |
| `blocks`    | Every new chain head.                                   |
| `token:0x…` | Launches, trades and phase changes for that token only. |

## The messages

Each has a `type`.

**`block`** — a new head, twice a second.

```json
{ "type": "block", "number": "21185211", "timestamp": 1789575871, "baseFeePerGas": "23000000000" }
```

`number` is what you add one to when pricing a buy. `baseFeePerGas` is what you size a gas reserve against; it is not fixed, so do not cache it.

**`trade`** — a trade, as soon as it is indexed.

```json
{
  "type": "trade",
  "trade": { "token": "0x…", "side": "buy", "trader": "0x…", "quoteAmount": "…", "…": "…" },
  "priceX18": "47195208398326",
  "realQuote": "6486000000000000000000"
}
```

`priceX18` and `realQuote` are the curve after the trade, so you can update a chart and a progress bar without re-reading the launch.

**`launch`** — a new token, in the same shape as `GET /launches/{token}`.

**`phase`** — a launch changed phase.

```json
{ "type": "phase", "token": "0x…", "phase": "pool" }
```

`pool` means it graduated: stop quoting against the curve and follow `graduation.pool`. See [Graduation](/integration/graduation.md).

## Staying connected

The socket is stateless: the server keeps your channel list and nothing else. If it drops, reconnect and subscribe again. Nothing is replayed, so on reconnect re-read what you missed over HTTP, then resume.

Blocks are the heartbeat. If none arrives for more than a few seconds, the connection is dead even though it has not said so. Treat that silence as a disconnect and reconnect rather than waiting for a close event.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.surged.fun/integration/api/realtime.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.