---
url: /api/streaming.md
description: >-
  SSE live feed — connect, receive, Last-Event-ID resume, 30s auth re-check,
  5-min recycle, and the full per-event catalog with example payloads.
---

# Streaming (SSE)

`GET /api/v1/stream` is a [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) feed. It delivers real-time events as your trading engine produces them — position updates, order fills, TP hits, trade lifecycle changes, and more.

***

## Connecting

```bash
curl -N https://app.telegramtometatrader.com/api/v1/stream \
  -H "Authorization: Bearer ttmt_live_…" \
  -H "Accept: text/event-stream"
```

Optional: filter to one account:

```bash
curl -N "https://app.telegramtometatrader.com/api/v1/stream?account_id=a1b2c3d4-..." \
  -H "Authorization: Bearer ttmt_live_…" \
  -H "Accept: text/event-stream"
```

The `account_id` must be the **DB UUID** from `GET /accounts`, not the MetaAPI string ID.

Each event arrives as:

```
id: 42
data: {"type":"tp_hit","eventId":42,"timestamp":"2026-06-09T14:32:01.123Z","data":{...}}
```

***

## Connection lifecycle

### 30-second auth re-check

Every 30 seconds the stream re-validates your key and account access against the database. If your key was revoked or account access was disabled in that window, the stream emits an `auth_revoked` event and closes. This means revocation cuts off an active stream within 30 seconds.

The check fails-open on transient database errors — a brief Supabase blip will not disconnect a valid stream.

### 5-minute forced recycle

The stream has an explicit 5-minute lifetime. Before closing, it emits a `recycle` event:

```json
{
  "type": "recycle",
  "reason": "max_lifetime"
}
```

Then the connection closes. Your client should reconnect immediately, sending the last received `id` as `Last-Event-ID`.

### Reconnect with Last-Event-ID

The server keeps a short buffer of recent events (currently the last 100). When you reconnect with `Last-Event-ID: N`, the server replays any buffered events your client missed. For gaps beyond the buffer, fall back to REST polling.

```bash
curl -N https://app.telegramtometatrader.com/api/v1/stream \
  -H "Authorization: Bearer ttmt_live_…" \
  -H "Last-Event-ID: 41"
```

Browser `EventSource` sends `Last-Event-ID` automatically. In Node.js or Python, you need to track the last `id` value and include it on reconnect.

***

## Error responses

| Code | Reason |
|:---|:---|
| `401` | Invalid or revoked key |
| `409` | Another stream is already open for this key |
| `503` | Your trading container is not running — REST history still works |

***

## Signal provenance

Every event that touches a position or trade carries a `signal` sub-object identifying the Telegram message that originated the trade:

```json
{
  "signal": {
    "signal_id": "f3c1a2b4-uuid",
    "telegram_message_id": 12345
  }
}
```

`signal` is `null` when:

* The trade has no signal FK (manual or legacy trade)
* The originating signal was soft-deleted
* The event was emitted before the watchdog cache was populated

`breakeven_set` always has `signal: null` — see [breakeven\_set](#breakeven-set) below.

***

## Event catalog

All events share a common outer envelope:

```json
{
  "type": "...",
  "eventId": 42,
  "timestamp": "2026-06-09T14:32:01.123Z",
  "userId": "uuid",
  "data": { ... }
}
```

***

### position\_update

Fired continuously (throttled) as positions move. Use this to update unrealized P\&L in your UI. The `data` may contain either a single position delta or a batch of positions.

**Single position delta:**

```json
{
  "type": "position_update",
  "eventId": 10,
  "timestamp": "2026-06-09T14:32:01.123Z",
  "data": {
    "positionId": "abc-metaapi-id",
    "symbol": "XAUUSD",
    "unrealizedProfit": 42.50,
    "currentPrice": 3312.80,
    "accountId": "a1b2c3d4-uuid",
    "signal": {
      "signal_id": "f3c1a2b4-uuid",
      "telegram_message_id": 12345
    }
  }
}
```

**Batch positions update:**

```json
{
  "type": "position_update",
  "eventId": 11,
  "timestamp": "2026-06-09T14:32:01.456Z",
  "data": {
    "positions": [
      {
        "id": "abc-metaapi-id",
        "symbol": "XAUUSD",
        "unrealizedProfit": 42.50,
        "currentPrice": 3312.80
      }
    ],
    "accountId": "a1b2c3d4-uuid"
  }
}
```

***

### order\_fill

Fired when a limit order fills (a layer entry executes).

```json
{
  "type": "order_fill",
  "eventId": 15,
  "timestamp": "2026-06-09T14:33:00.000Z",
  "data": {
    "orderId": "order-metaapi-id",
    "positionId": "pos-metaapi-id",
    "symbol": "XAUUSD",
    "volume": 0.03,
    "fillPrice": 3310.50,
    "layer": 2,
    "accountId": "a1b2c3d4-uuid",
    "signal": {
      "signal_id": "f3c1a2b4-uuid",
      "telegram_message_id": 12345
    }
  }
}
```

***

### position\_closed

Fired when a position closes (TP hit, SL hit, manual close, breakeven, trailing stop).

```json
{
  "type": "position_closed",
  "eventId": 20,
  "timestamp": "2026-06-09T14:35:00.000Z",
  "data": {
    "positionId": "pos-metaapi-id",
    "reason": "tp_hit",
    "tradeId": "trade-db-uuid",
    "accountId": "a1b2c3d4-uuid",
    "signal": {
      "signal_id": "f3c1a2b4-uuid",
      "telegram_message_id": 12345
    }
  }
}
```

***

### trade\_executed

Fired when a new trade is opened (the signal was processed and orders were placed).

```json
{
  "type": "trade_executed",
  "eventId": 5,
  "timestamp": "2026-06-09T14:30:00.000Z",
  "data": {
    "tradeId": "trade-db-uuid",
    "symbol": "XAUUSD",
    "channelName": "Gold Signals Pro",
    "positionsCount": 3,
    "ordersCount": 10,
    "accountId": "a1b2c3d4-uuid",
    "signal": {
      "signal_id": "f3c1a2b4-uuid",
      "telegram_message_id": 12345
    }
  }
}
```

***

### trade\_finalized

Fired when a trade reaches a terminal state (all positions closed, P\&L computed).

```json
{
  "type": "trade_finalized",
  "eventId": 25,
  "timestamp": "2026-06-09T14:40:00.000Z",
  "data": {
    "tradeId": "trade-db-uuid",
    "status": "closed_profit",
    "profitLoss": 87.20,
    "accountId": "a1b2c3d4-uuid",
    "signal": {
      "signal_id": "f3c1a2b4-uuid",
      "telegram_message_id": 12345
    }
  }
}
```

***

### tp\_hit

Fired when a take-profit level is hit and partial orders close.

```json
{
  "type": "tp_hit",
  "eventId": 18,
  "timestamp": "2026-06-09T14:34:00.000Z",
  "data": {
    "tradeId": "trade-db-uuid",
    "tpLevel": "TP2",
    "accountId": "a1b2c3d4-uuid",
    "signal": {
      "signal_id": "f3c1a2b4-uuid",
      "telegram_message_id": 12345
    }
  }
}
```

***

### breakeven\_set

Fired when stop-loss is moved to breakeven on a position.

::: info signal is always null for this event
`breakeven_set` carries a DB position UUID (not the MetaAPI position ID). The signal lookup requires the MetaAPI ID, so `signal` is always `null` here.
:::

```json
{
  "type": "breakeven_set",
  "eventId": 19,
  "timestamp": "2026-06-09T14:34:30.000Z",
  "data": {
    "positionId": "pos-db-uuid",
    "newSL": 3310.00,
    "accountId": "a1b2c3d4-uuid",
    "signal": null
  }
}
```

***

### breakeven\_failed

Fired when a breakeven attempt fails (broker rejected the SL modification).

```json
{
  "type": "breakeven_failed",
  "eventId": 22,
  "timestamp": "2026-06-09T14:34:45.000Z",
  "data": {
    "tradeId": "trade-db-uuid",
    "positionId": "pos-db-uuid",
    "accountId": "a1b2c3d4-uuid",
    "signal": {
      "signal_id": "f3c1a2b4-uuid",
      "telegram_message_id": 12345
    }
  }
}
```

***

### auth\_revoked

Fired by the 30-second auth re-check when your key is revoked or access is disabled. The stream closes immediately after.

```json
{
  "type": "auth_revoked",
  "eventId": 99,
  "timestamp": "2026-06-09T15:00:00.000Z",
  "data": {
    "reason": "key_revoked"
  }
}
```

`reason` is `"key_revoked"` or `"access_disabled"`.

***

### recycle

Fired before the server-initiated 5-minute recycle close. Reconnect immediately.

```json
{
  "type": "recycle",
  "eventId": 100,
  "timestamp": "2026-06-09T14:35:00.000Z",
  "data": {
    "reason": "max_lifetime"
  }
}
```

***

## Recommended client pattern

Connect, track the last event ID, reconnect on close, fall back to REST on reconnect failure:

```javascript
const BASE = "https://app.telegramtometatrader.com/api/v1"
const KEY = "ttmt_live_…"

let lastEventId = null

function connect() {
  const headers = {
    "Authorization": `Bearer ${KEY}`,
    "Accept": "text/event-stream",
    ...(lastEventId ? { "Last-Event-ID": lastEventId } : {})
  }

  // fetch-based SSE (Node 18+, browsers)
  fetch(`${BASE}/stream`, { headers })
    .then(resp => {
      if (!resp.ok) throw new Error(`${resp.status}`)
      const reader = resp.body.getReader()
      const decoder = new TextDecoder()

      function read() {
        return reader.read().then(({ done, value }) => {
          if (done) { reconnect(); return }
          const text = decoder.decode(value)
          parseSSE(text)
          return read()
        })
      }
      return read()
    })
    .catch(() => reconnect())
}

function parseSSE(text) {
  for (const line of text.split("\n")) {
    if (line.startsWith("id: ")) lastEventId = line.slice(4).trim()
    if (line.startsWith("data: ")) {
      const event = JSON.parse(line.slice(6))
      handleEvent(event)
    }
  }
}

function reconnect() {
  setTimeout(connect, 2000)  // 2s back-off
}

connect()
```

## Related pages

* [API Quickstart](/api/quickstart) — from API access to your first response in five steps
* [Authentication](/api/authentication) — managing API keys and access lifecycle
* [Rate Limiting](/api/rate-limiting) — request limits and `429` handling
* [Errors](/api/errors) — error response format and codes
* [Endpoint Reference](/api/reference/) — the full API endpoint catalog
