• Reading the docs…
Start trading

API reference

Events

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: cursor is not an unsigned integer, pair is not a pair id, or the query carries another key.
  • NOT_FOUND: no market has this pair.
  • CONFIGURATION_REQUIRED or UPSTREAM_UNAVAILABLE: the API could not look up pair, as on GET /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.

TypeScript
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
      }
    }
  })
}

Every connection opens with ready, carrying the countdown and the cursor. Captured on its own:

Response
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.

Response
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.