Streaming: WebSocket and SSE

Stop polling. Two endpoints on the intelligence service push flag events as they are detected.

Path	Transport	Direction	Use when
`/ws/flags`	WebSocket (RFC 6455)	bidirectional	you want to change your chain filter without reconnecting
`/sse/flags`	server-sent events	server to client	your network strips `Upgrade`, or your client has no WebSocket

wss://scienter-intelligence-production.up.railway.app/ws/flags
https://scienter-intelligence-production.up.railway.app/sse/flags

How live is “live”

There is no push path from the rug model into the streaming process. The model writes rows to a table; the stream polls that table every 60 seconds and publishes the difference.So a flag reaches you in up to one poll interval, not instantly. Every welcome event carries source.poll_interval_s so you can see the real number rather than assuming zero.

This is a deliberate, documented property, not a defect being hidden. When the model gains a push path the interval goes to zero and poll_interval_s will say so — your client needs no change.

Connect

// The browser WebSocket constructor takes no headers, so the token goes in
// the query string. See "Authentication" below for what that costs.
const ws = new WebSocket(
  'wss://scienter-intelligence-production.up.railway.app/ws/flags?token=YOUR_TOKEN'
)

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data)
  if (msg.type === 'rug_flag') {
    console.log(msg.chain, msg.address, msg.score)
  }
}

// Narrow the feed at any time, without reconnecting.
ws.onopen = () => ws.send(JSON.stringify({ subscribe: ['ethereum', 'solana'] }))

# pip install websocket-client
import json
import websocket

URL = "wss://scienter-intelligence-production.up.railway.app/ws/flags"

ws = websocket.create_connection(
    URL, header=["Authorization: Bearer YOUR_TOKEN"]
)
ws.send(json.dumps({"subscribe": ["ethereum"]}))

while True:
    msg = json.loads(ws.recv())
    if msg["type"] == "rug_flag":
        print(msg["chain"], msg["address"], msg["score"])

curl -N \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://scienter-intelligence-production.up.railway.app/sse/flags?chains=ethereum,solana"

// EventSource reconnects on its own and replays Last-Event-ID, so a dropped
// connection resumes without a gap. It cannot set headers either.
const es = new EventSource(
  'https://scienter-intelligence-production.up.railway.app/sse/flags?token=YOUR_TOKEN'
)

es.addEventListener('rug_flag', (e) => {
  const msg = JSON.parse(e.data)
  console.log(msg.chain, msg.address, msg.score)
})

Authentication

The token goes in an Authorization: Bearer header, or as ?token= for clients that cannot set headers — which includes every browser, because the WebSocket and EventSource constructors take a URL and nothing else.

Mint a separate token for streaming. A token in a URL is written to the platform’s access log, to any proxy in front of it, to the browser’s history, and to the Referer of anything the page loads afterwards. Its exposure surface is larger than a REST token’s, so it should be revocable on its own.The service redacts the value from its own logs. It cannot redact it from anybody else’s.

The header is checked first and always wins. Use it wherever you can.

Concurrent connection limits

Counted per credential, not per tier — the hundred-and-first Pro customer is never refused because of a stranger.

Tier	Concurrent streams
Free	10
Pro	100
Team	500
Enterprise	Unlimited

Over the limit, the connection is refused with 429 before the WebSocket handshake completes, and the body says which limit you hit:

{
  "state": "at_capacity",
  "error": "too_many_connections",
  "scope": "pro",
  "limit": 100,
  "current": 100,
  "reason": "the pro tier allows 100 concurrent streams"
}

A scope of "instance" rather than a tier name means the server is full, not your plan. Retry; it is not a billing problem.

Filtering by chain

Set the initial filter in the query string, on either transport:

/ws/flags?chains=ethereum,solana
/sse/flags?chains=base

Omit it to receive every chain. On WebSocket you can also change it in place:

{ "subscribe": ["ethereum", "solana"] }
{ "subscribe": "all" }

The server replies with a subscribed event carrying the resolved filter. Chain names not scored by this service are reported, not silently dropped:

{
  "type": "error",
  "error": "no_valid_chains",
  "rejected": ["etherium"],
  "known_chains": ["ethereum", "solana", "base", "bsc", "arbitrum", "hyperevm", "bitcoin"],
  "chains": ["ethereum"]
}

Your existing filter is left alone when every requested name is rejected — a typo must not silently switch you to “everything” and a surprise bill.

SSE is one-way. Its filter is fixed for the life of the connection; reconnect with a different ?chains= to change it, or use /ws/flags.

Event types

Every event carries seq, type and ts. Chain-scoped events also carry chain.

`type`	Meaning
`welcome`	Sent once on connect, before any backlog. Your tier, filter, and how live the feed is
`rug_flag`	A wallet crossed the flag threshold, or an existing one was re-scored
`subscribed`	Acknowledges a `subscribe` message with the resolved filter
`heartbeat`	Every 30 seconds of silence
`lag`	You fell behind and events were dropped. Carries the exact range
`error`	A malformed message or an unknown chain. The connection stays open

`rug_flag`

{
  "seq": 4103,
  "type": "rug_flag",
  "ts": 1788461237.42,
  "chain": "ethereum",
  "address": "0x0000000000000000000000000000000000000000",
  "score": 91.0,
  "first_flagged_at": "2026-09-03T09:00:00Z",
  "last_scored_at": "2026-09-03T10:00:00Z",
  "model_version": "v20260901_180251",
  "top_evidence": { "feature": "liquidity_pull", "value": 0.94 },
  "first_seen": true
}

first_seen: false means an existing flag was re-scored. A wallet moving from 62 to 91 is usually the event you most want, so re-scores are published rather than deduplicated away. top_evidence is the single top factor, not the full attribution. For the complete explanation read /api/token/{address}/rug-score, where it is authoritative.

Resuming without a gap

Every event carries a monotonic seq. Reconnect with the last one you saw:

/ws/flags?since=4102
/sse/flags?since=4102

EventSource does this for you — it sends Last-Event-ID, which the server treats identically. The replay window is bounded. If you ask for a range that has already been discarded, welcome carries a gap:

{ "gap": { "from_seq": 4103, "to_seq": 5310 } }

Those events are gone from the stream. Re-read the range from the REST API.

Backpressure

Each connection buffers 1,000 events. If you stop reading, the oldest are dropped — you get the current state of the world rather than a backlog you will never catch up on — and you are told exactly what you lost:

{
  "seq": 5311,
  "type": "lag",
  "from_seq": 4103,
  "to_seq": 5310,
  "dropped": 1208,
  "reason": "subscriber_buffer_overflow"
}

The lag event arrives before the event on the far side of the gap, so a jump in seq is never ambiguous. One slow subscriber costs the others nothing.

Heartbeats

Every 30 seconds of silence you get a heartbeat event, and on WebSocket a protocol-level ping as well. Both, because the JSON one is what your application can act on and the ping is what stops an intermediary reaping an idle connection. If you see neither for 90 seconds, the connection is dead — reconnect with ?since=.

Why the feed may be empty

An empty feed and a broken feed look identical unless you check. welcome tells you which one you have:

{
  "source": {
    "kind": "poll",
    "poll_interval_s": 60,
    "primed": true,
    "unavailable_reason": null
  }
}

primed: false — the poller has not completed a first read. Nothing has been checked yet.
unavailable_reason non-null — the flag table could not be read. This is not a quiet day; nothing looked.

A subscriber who cannot tell “no wallets were flagged” from “wallets were flagged and you did not get them” is being sold the first while receiving the second. That is why the reason is on the wire.

Reaching `/ws/flags` over plain HTTP

You get a 426 with the URL you actually wanted, rather than a bare error:

{
  "state": "upgrade_required",
  "reason": "this endpoint speaks WebSocket; connect with wss://",
  "websocket_url": "wss://scienter-intelligence-production.up.railway.app/ws/flags",
  "sse_url": "https://scienter-intelligence-production.up.railway.app/sse/flags"
}

Known limitations

Single instance. The event bus is in one process’s memory. The service runs one replica for this reason. Scaling out requires a shared log first — see ADR 0001 in the repository.
HEAD answers 501 on the deployed service — on every route, including /health. That handler defines no HEAD method and never has. Use GET.
The feed is only as populated as its source. Production currently serves no_snapshot on the flag table because its database credentials are unset, so the stream connects, authenticates, heartbeats, and reports unavailable_reason rather than delivering flags. Reported honestly rather than as a quiet day.
No permessage-deflate. Payloads are small JSON objects; the extension is opt-in and declining it is conformant.

Scienter publishes impersonal market signals of general and regular circulation. Nothing here is investment, legal, or tax advice, or a recommendation to buy, sell, or hold any asset. Scienter is not a registered investment adviser or broker-dealer. Trading digital assets can result in the total loss of your funds — see Disclaimers for the full text.

Using the API

Streaming

Intelligence service

Public HTTP endpoints

Self-hosted endpoints

MCP tools

Streaming: WebSocket and SSE

How live is “live”

Connect

Authentication

Concurrent connection limits

Filtering by chain

Event types

`rug_flag`

Resuming without a gap

Backpressure

Heartbeats

Why the feed may be empty

Reaching `/ws/flags` over plain HTTP

Known limitations

​How live is “live”

​Connect

​Authentication

​Concurrent connection limits

​Filtering by chain

​Event types

​rug_flag

​Resuming without a gap

​Backpressure

​Heartbeats

​Why the feed may be empty

​Reaching /ws/flags over plain HTTP

​Known limitations

How live is “live”

Connect

Authentication

Concurrent connection limits

Filtering by chain

Event types

`rug_flag`

Resuming without a gap

Backpressure

Heartbeats

Why the feed may be empty

Reaching `/ws/flags` over plain HTTP

Known limitations