Publish a single event from a partner firm into the tower stream.
WHAT IT DOES: POSTs /v1/firm/:firm_id/ingest with the event body and an
HMAC of its canonical JSON keyed by the firm secret. Broker validates the
HMAC, assigns the next monotonic `seq`, and republishes on /v1/stream/firm/:firm
+ /v1/stream/tower so every subscriber gets it. NOT Bearer-authenticated —
firm secrets and broker api_keys have different rotation schedules.
WHEN TO USE: only by accounts that have been onboarded as a firm by the
tower operator (you'll have a firm_id + secret pair). Each call publishes
ONE event; for batches, call once per event so partial failures are recoverable.
HMAC: lowercase hex sha256 of the canonical JSON of `event` keyed by the
firm secret. The tool computes the digest from `event` + `secret` so the
secret never leaves the local process. The secret itself is NOT sent to
the broker — only the digest.
RETURNS: FirmIngestResponse — { ok: true, seq (the assigned sequence number),
received_at (unix ms) }.
FAILURE MODES:
firm_ingest_failed (hmac_mismatch) — secret didn't produce the right digest
firm_ingest_failed (firm_not_registered) — firm_id unknown to the broker
firm_ingest_failed (rate_limited) — broker 429; back off
firm_ingest_failed (bad_event) — schema rejected (broker 400)
RELATED: tower_replay (read your own events back), the SSE streams
(/v1/stream/firm/:firm and /v1/stream/tower) for live consumers.
Connector