React to what happens, instead of polling for it.

Interpose is event-sourced: every fill, position change and rebalance is published as an immutable event, and positions are derived by folding those events. Your systems can subscribe to that stream rather than asking for changes on a timer — which is the difference between noticing a fill at 09:00 tomorrow and noticing it at 14:23:07 today.

Two transports are reachable from your own infrastructure. Server-Sent Events is ordinary HTTP and needs nothing but a bearer token. WebSocket costs one extra call — you mint a single-use ticket first — and gives you a socket a browser can open too. For higher volume, Kafka is available by arrangement. The ledger behind all three is durable and append-only; the stream is a live view of it, not a replay log.

Transport availability

Server-Sent Events

Seven streams are registered under BaaS, all reachable at the normal public base URL. They are ordinary HTTP — no upgrade, no ticket, no special client — which makes them the shortest path to a working integration, and the transport that survives a corporate proxy refusing to upgrade a connection. The four below are the ones to build on:

Three more are registered and will connect. /events/funding/status and /events/journals/status have emitters behind them and carry real traffic; /events/system has no emitter at all, so it connects and stays empty.

curl -N -H "Authorization: Bearer $TOKEN" \
     -H "Accept: text/event-stream" \
     https://interposehq.com/api/v1/baas/events/trades

The response is text/event-stream; the connection stays open and each event arrives as a data: line carrying the CloudEvents envelope. Use -N with curl, or disable buffering in your client, or you will see nothing until the buffer flushes.

import httpx, json

with httpx.stream("GET", "https://interposehq.com/api/v1/baas/events/trades",
                  headers={"Authorization": f"Bearer {token}",
                           "Accept": "text/event-stream"},
                  timeout=None) as r:
    for line in r.iter_lines():
        if line.startswith("data:"):
            event = json.loads(line[5:])
            print(event["type"], event["id"])

The stream is scoped to your book

Every event is filtered against the same authorization predicate that guards the REST route for the account it belongs to, so a connection carries your firm's events and no one else's. The account_id query parameter narrows it further and now matches — it reads data.account_id off the envelope, which is where the platform actually puts it. Naming an account you are not entitled to returns 403 rather than an empty stream.

curl -N -H "Authorization: Bearer $TOKEN" \
     -H "Accept: text/event-stream" \
     'https://interposehq.com/api/v1/baas/events/trades?account_id=acct_01HV4Y...'

WebSocket

The WebSocket streams are reachable at the public base URL. A handshake carries no Authorization header — the browser WebSocket constructor takes a URL and a subprotocol list and nothing else — so you exchange your ordinary credential for a single-use ticket over REST first, then connect with that.

curl -X POST https://interposehq.com/api/v1/baas/stream/tickets \
  -H "Authorization: Bearer $TOKEN"

{"ticket": "eyJhbGciOiJIUzI1NiIs...", "token_type": "ws_ticket", "expires_in": 60}

import asyncio, json, httpx, websockets

BASE = "https://interposehq.com/api/v1/baas"

ticket = httpx.post(f"{BASE}/stream/tickets",
                    headers={"Authorization": f"Bearer {token}"}).json()["ticket"]

async def main():
    async with websockets.connect(f"wss://interposehq.com/api/v1/baas/stream?ticket={ticket}") as ws:
        await ws.send(json.dumps({"action":     "subscribe",
                                  "account_id": "acct_01HV4Y2K3M5N8P9QR2ST4UVWXY"}))
        print(json.loads(await ws.recv()))
        # {"type": "subscribed", "account_id": "acct_01HV4Y2K3M5N8P9QR2ST4UVWXY"}

        async for message in ws:
            frame = json.loads(message)
            print(frame["type"], frame.get("data"))

asyncio.run(main())

The reason for the extra call rather than ?token=<your portal JWT>: the application server logs the handshake path including its query string, and a portal token is valid for eight hours — so a logged URL would be a session handover. A spent 60-second ticket in the same log line is worth nothing.

One round trip, and from a browser

A browser cannot set a header on a handshake but can offer subprotocols, so the ticket may travel there instead. That form keeps it out of the access log altogether.

const { ticket } = await (await fetch("/api/v1/baas/stream/tickets", {
  method:  "POST",
  headers: { Authorization: `Bearer ${token}` },
})).json();

const ws = new WebSocket("wss://interposehq.com/api/v1/baas/stream",
                         ["interpose.v1", `interpose.token.${ticket}`]);

ws.onopen = () => ws.send(JSON.stringify({
  action: "subscribe", account_id: "acct_01HV4Y2K3M5N8P9QR2ST4UVWXY",
}));

Subscribing, and what a refusal looks like

Send {"action": "subscribe", "account_id": "acct_..."} within ten seconds of connecting and the server answers {"type": "subscribed", "account_id": "acct_..."}. Every subscribe frame is authorized against the same predicate as the REST route for that account, so a socket can only ever carry a book your credential could already read. One account per connection — open a second socket for a second account.

The CloudEvents envelope

Server-Sent Events and Kafka both carry CloudEvents 1.0 — the same envelope, byte for byte, whichever you consume. The two senders that use their own shape are the WebSocket frame above and the webhook delivery below, and each says so where it is documented.

{
  "specversion": "1.0",
  "type":        "com.interpose.baas.order.filled",
  "source":      "com.interpose.baas",
  "id":          "evt_01HV4Y2K3M5N8P9QR2ST4UVWXY",
  "time":        "2026-05-11T14:23:00.000000000Z",
  "datacontenttype": "application/json",
  "issandbox":   true,
  "data": {
    "order_id":        "ord_01HV4Y...",
    "account_id":      "acct_01HV4Y...",
    "security":        { "type": "ticker", "value": "AAPL" },
    "side":            "BUY",
    "filled_quantity": "10.00000000",
    "avg_fill_price":  "182.4500",
    "currency":        "USD"
  }
}

There is no com.interpose.crypto.* namespace — crypto events are emitted under their owning pillar like everything else. New attributes are added inside the envelope without a version bump, so ignore unknown fields. Order holds within a partition; it does not hold across topics.

Event types you can rely on

Consuming Kafka directly

For higher-volume integrations, direct topic consumption avoids delivery overhead entirely. The broker is self-hosted; connection details and credentials are arranged during onboarding, and there is no self-serve path. Use your own consumer group id, start from latest unless you have a reason to replay, and expect the CloudEvents envelope above as the JSON payload.

Webhooks

Webhook registration works today and event dispatch does not — the detail is in Current limits. The signature scheme below is documented because it is what you will verify against once dispatch ships, and because the one signed sender that is live — the professional-network subscription feed — already uses it.

{timestamp}.{raw_request_body}

import hashlib, hmac, time, json

MAX_AGE_SECONDS = 300

def verify(raw: bytes, ts: str, sig: str, secret: str) -> dict:
    expected = hmac.new(secret.encode(), f"{ts}.".encode() + raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, sig):
        raise ValueError("bad signature")
    if abs(time.time() - float(ts) / 1000) > MAX_AGE_SECONDS:   # ts is in MILLISECONDS
        raise ValueError("stale delivery")
    return json.loads(raw)

Three further rules, each of which has burned somebody: verify the raw body before parsing, because re-serialising JSON changes the bytes; reject deliveries older than five minutes, because a valid signature on a replayed message is still a replay; and use constant-time comparison, because == on a signature is a timing oracle.

The delivery body is not a CloudEvent

Kafka and SSE carry the CloudEvents envelope. The webhook sender posts its own shape:

{
  "delivery_id": "dlv_01HV4Y2K3M5N8P9QR2ST4UVWXY",
  "event_type":  "consent.granted",
  "severity":    "INFO",
  "payload":     { },
  "occurred_at": "2026-05-11T14:23:00.000000000Z"
}

Dedupe on delivery_id. There is no id, specversion or type field to key on — those belong to the CloudEvents envelope, not to this one. Return 2xx quickly: acknowledge, enqueue, and do the work asynchronously.