One Server-Sent Events stream of the Pool’s public activity and every account’s sealed replies. Every reader receives the same events, and none of them names an owner.
Route#
GET /v1/events#
Streams the next cutoff, committed Crossings with their Ledger diffs, mids and sealed replies as they happen. watchEvents reads it, and watchFills keeps the encrypted events that open under the account’s keys; the Account page follows its fills that way.
| Parameter | Type | In | Meaning |
|---|---|---|---|
cursor |
string (optional) |
query | The last Crossing the reader holds, as a Ledger diff cursor: on connecting, the stream sends each committed Crossing after it with its diff, as many as one diff page holds. |
pair |
string (optional) |
query | The market whose mids the stream sends; without it, the stream sends every mid the API publishes. |
Returns text/event-stream. Each event’s data is one LiveEvent.
Errors
VALIDATION_ERROR:cursoris not an unsigned integer,pairis not a pair id, or the query carries another key.NOT_FOUND: no market has thispair.CONFIGURATION_REQUIREDorUPSTREAM_UNAVAILABLE: the API could not look uppair, as onGET /v1/markets/{pair}.INDEXER_UNAVAILABLE: the indexer has not verified the latest Commit yet, or its root disagrees with the chain; retryable.PROGRAM_UNAVAILABLE: the Pool is not indexed yet; retryable.
An error arrives as the envelope before the stream opens. Once open, the stream only ends.
import { SdkError } from '@privium/sdk'
import { LiveEvent } from '@privium/sdk/contract'
// The cursor of the last Ledger diff this reader verified.
declare const lastVerified: string
const { items } = await api.markets({ q: 'SOL', quote: 'USDC' })
const stream = new EventSource(api.eventsUrl({ cursor: lastVerified, pair: items[0].pair }))
for (const type of ['ready', 'crossing', 'mid', 'ledger', 'encrypted', 'resync']) {
stream.addEventListener(type, async (message) => {
const event = LiveEvent.parse(JSON.parse((message as MessageEvent<string>).data))
if (event.type === 'resync') console.log('Refetch snapshots, then scan diffs from the last verified cursor.')
if (event.type === 'encrypted') {
try {
const result = await privium.decodeEnvelope(event.data.envelope)
console.log(result.kind)
} catch (error) {
if (!(error instanceof SdkError && error.code === 'DECRYPTION_FAILED')) throw error
}
}
})
}
curl -N 'https://api.privium.io/v1/events?cursor=54&pair=So11111111111111111111111111111111111111112_EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'
Every connection opens with ready, carrying the countdown and the cursor. Captured on its own:
event: ready
data: {"type":"ready","id":"1794908565997-494","timestamp":"2026-11-17T09:42:45.997Z","data":{"countdown":{"currentSlot":"470885296","lastCommitSlot":"470884581","deltaSlots":4,"nextCutoffSlot":"470885297","slotTimeMs":200,"observedAt":"2026-11-17T09:42:45.997Z"},"cursor":"16"}}
id: 1794908565997-494
A longer capture, from its first event after ready: the stream caught up Crossing 55, then sent the pair’s mid each second. When Crossing 56 committed, the reply the enclave issued at its Commit went out as an encrypted event, and the Crossing followed with its diff. The capture keeps the first of the mids and ends at Crossing 56; its two ledger events, about 166 KB each, are cut.
event: crossing
data: {"type":"crossing","id":"1794895866575-116","timestamp":"2026-11-17T06:11:06.575Z","data":{"index":"55","slot":"470449426","time":"2026-11-17T06:11:04.000Z","pairs":[],"crossedNotionalUsd":{"value":"0","unavailableReason":null},"routedNotionalUsd":"0","residuals":[],"fees":[],"commitTransaction":"3DY8pzJPos2ZkWYegbmF5R8cMy5LaUL5CptF4VKeMTzwmCZxESQAkGN6EiqzZKTXvE1MPsMJUkah5anT7Pu6xwxC","root":"Cvn6H6z2LPQOJdnsTAX3rBx7RfCuXHtOB0Q/scbPq1U=","diffHash":"y6DKYLgQliitATcQYk2qGpQNNulmirD2OajN6Aq97ak="}}
id: 1794895866575-116
event: mid
data: {"type":"mid","id":"1794895867494-121","timestamp":"2026-11-17T06:11:07.494Z","data":{"pair":"So11111111111111111111111111111111111111112_EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","mid":{"price":"71.5185","source":"pyth","observedAt":"2026-11-17T06:11:06.000Z","ageMs":1494,"confidenceBps":1,"stale":false}}}
id: 1794895867494-121
event: encrypted
data: {"type":"encrypted","id":"1794895869548-126","timestamp":"2026-11-17T06:11:09.548Z","data":{"envelope":"SA9NmmHRsDG2cNJxufmoAlXg1CLFgmZ/UOWnaOlo/h8CDa+vHzSGHtf+h0Q8NEJNDua+kuIndsWCki/N5HUmpb4yu8Nl4QHe4pxV0WKCsD2CqzmVupMBM/ReP2FWz82jCQxLdVR2pcm5bDmpySi3gbhkmwe8R5YuDRYBlboYjL8Pmh9USEhnCbyMaGd/ESGjEk3PUVs0tjqeoYwvefrSppIx2yB8kPVA5Q19Y3UB4omgoPuPftKdFeHMJ97UYivxdA/n+7PJLINMleAY9DCdcRcrtnx5kqYvBuuKV3cEiLT5IQudJ7YlELRan19ovqB+370XOw3eXerhAqMWVWEiAKb7GqZNF0wgl5TTHtK5pEcJezGho0HoXGakFF8yXDW5msXILiQ9j4zddNL92atVU647GUQZpe6WSDSW","crossing":"56","cursor":"49"}}
id: 1794895869548-126
event: crossing
data: {"type":"crossing","id":"1794895869555-127","timestamp":"2026-11-17T06:11:09.555Z","data":{"index":"56","slot":"470449445","time":"2026-11-17T06:11:08.000Z","pairs":[],"crossedNotionalUsd":{"value":"0","unavailableReason":null},"routedNotionalUsd":"0","residuals":[],"fees":[],"commitTransaction":"4p1pjdDeq9kicE12TwchJ6dNKVQ7VMCNFudu1uuMoRvhD2rXZETM79uM6k6v1D2XA3ug85JansKQJhyGKjP7gSph","root":"5cQLiI2m1BGI5TBlQJvXmkYvAbVjheg+7qls9QUYmRM=","diffHash":"KkxsBdtCeFni2tO9tlw/F666QrENt9m+tSnAzMyvKcI="}}
id: 1794895869555-127
Framing#
Each event is three lines and a blank line: event: with the type, data: with the whole LiveEvent as one line of JSON, and id: with the event’s id. The data line carries the type again, so a reader can parse it alone. An EventSource needs a listener per type, since named events never reach onmessage.
| When | What the stream sends |
|---|---|
| On connecting | ready with the countdown and the stream’s tip, the latest committed Crossing. With cursor, each committed Crossing after it up to the tip follows, a crossing event and its ledger diff, as long as they fit one diff page: at most 100 Crossings and 2 MiB of diffs (Pages). A reader further behind gets one resync with reason behind instead and scans the rest with GET /v1/ledger/diffs |
| As it happens | each later Crossing as a crossing event and its ledger diff once the indexer verifies its Commit; the mid of pair on each pass of the API’s update loop, which starts again a second after the last pass ends; each sealed reply as an encrypted event, both the replies intake returns and the replies the enclave issues at each Commit |
| After 15 seconds without an event | a : keepalive comment line, so proxies hold the connection open |
On a reconnect with Last-Event-ID |
resync with reason reconnected, then ready and the catch-up the URL’s cursor asks for. Nothing else is replayed |
| When 500 events wait for a slow reader | the queue is dropped for one resync with reason behind |
Without pair, the stream carries every mid the API publishes: the first page of markets, and each pair another reader’s stream selected.
On resync, refetch the snapshots on screen (the market panel, Pool, Trust and balances, through POST /v1/ledger/leaves) and continue a diff scan from your last verified cursor with GET /v1/ledger/diffs. An EventSource reconnects on its own and sends Last-Event-ID, so a dropped connection comes back as a resync. ready.cursor is the tip when the stream opened; keep your own last verified cursor rather than advancing it from ready.
There is no per-owner subscription. Every reader receives every encrypted event and tries each envelope with its own keys: decodeEnvelope opens one sealed to the account and throws DECRYPTION_FAILED for any other, and watchFills skips the others. The response carries Cache-Control: no-cache and X-Accel-Buffering: no.
Event types#
Every event has type, id, timestamp and data; type decides what data holds.
ready#
| Field | Type | Meaning |
|---|---|---|
ready.type |
"ready" |
ready. |
ready.id |
string |
The event id, also its SSE id line. |
ready.timestamp |
Timestamp |
When the server sent the event. |
ready.data |
object |
The stream's state. |
ready.data.countdown |
Countdown |
The earliest cutoff an Intent sent now can make. |
ready.data.cursor |
U64 |
The stream's tip: the latest committed Crossing when the stream opened, which is also its Ledger diff cursor. |
crossing#
| Field | Type | Meaning |
|---|---|---|
crossing.type |
"crossing" |
crossing. |
crossing.id |
string |
The event id, also its SSE id line. |
crossing.timestamp |
Timestamp |
When the server sent the event. |
crossing.data |
Crossing |
A committed Crossing. |
mid#
| Field | Type | Meaning |
|---|---|---|
mid.type |
"mid" |
mid. |
mid.id |
string |
The event id, also its SSE id line. |
mid.timestamp |
Timestamp |
When the server sent the event. |
mid.data |
object |
A market's mid. |
mid.data.pair |
PairId |
The market. |
mid.data.mid |
Mid |
Its mid. |
ledger#
| Field | Type | Meaning |
|---|---|---|
ledger.type |
"ledger" |
ledger. |
ledger.id |
string |
The event id, also its SSE id line. |
ledger.timestamp |
Timestamp |
When the server sent the event. |
ledger.data |
LedgerDiff |
A committed Ledger diff, as the diff scan serves it. |
encrypted#
| Field | Type | Meaning |
|---|---|---|
encrypted.type |
"encrypted" |
encrypted. |
encrypted.id |
string |
The event id, also its SSE id line. |
encrypted.timestamp |
Timestamp |
When the server sent the event. |
encrypted.data |
EncryptedEvent |
A sealed reply from the enclave. |
EncryptedEvent#
| Field | Type | Meaning |
|---|---|---|
envelope |
Base64 |
One sealed reply, base64. Only the account it was sealed to opens it; every other reader skips it. |
crossing |
U64 |
The Crossing the reply belongs to: the next Crossing for a reply intake returned, the committed one for a reply issued at its Commit. |
cursor |
U64 |
The reply's place in the enclave's reply sequence; for a reply intake returned, the next Crossing's index. |
resync#
| Field | Type | Meaning |
|---|---|---|
resync.type |
"resync" |
resync. |
resync.id |
string |
The event id, also its SSE id line. |
resync.timestamp |
Timestamp |
When the server sent the event. |
resync.data |
object |
Why to resync. |
resync.data.reason |
"reconnected", "behind" |
reconnected when the client resumed with Last-Event-ID; behind when 500 events waited for it, or when the Crossings after its cursor are more than one diff page holds. |
resync.data.cursor |
U64 |
The stream's tip, the latest committed Crossing when it opened. |