Draft Specification (Pre‑Production): This document reflects a work-in-progress wire format and API. It is subject to change without notice prior to general availability.

Quincy News API & Wire Format

Realtime access via multicast, WebSocket, or physical cross-connect. Designed for speed, simplicity, and extensibility.

DRAFTSpec v0.1

Delivery Options

Quincy News supports multiple delivery mechanisms to meet customer requirements:

Private cross-connect — direct physical connections in key colocations
Multicast over Layer 3 — the preferred method for deterministic feeds
WebSocket delivery — cloud-native and globally accessible

Our backbone spans data centers and clouds worldwide.

Common Message Header

All Quincy News messages begin with a compact and extensible 16-byte header:

struct MessageHeader {
  uint8_t  version;
  uint8_t  message_type;
  uint8_t  publisher_id;
  uint8_t  flags;           // future-use; send as 0; receivers MUST ignore unknown bits
  uint32_t sequence_number; // per-publisher, modulo 2^32
  uint32_t dedupe_id;       // 32-bit, time-window uniqueness target; 0 if unavailable
  uint32_t message_length;  // bytes of header + body
};

version: Upfront for fast conditional parsing.
message_type: Required to decode the message body.
publisher_id + sequence_number: Sequenced per publisher per multicast group.
flags: Reserved for future use. All bits MUST be ignored until defined.
dedupe_id: Independent content identity within a short time window (~100 ms). If not computed, set to 0.
message_length: Total message size in bytes, including this header and the body.

Wire Semantics & Conventions

Byte order & packing: All integers are unsigned and encoded in network byte order (big-endian). Fields are packed exactly as listed; there is no implicit struct padding on the wire.
Strings (fixed-width): UTF-8. By default, emitters use only single-byte characters (ASCII subset; one byte per character). If shorter than the field width, strings are NUL-terminated and remaining bytes are padding and MUST be ignored. If the field is fully occupied, it is not NUL-terminated. Future header flag(s) MAY announce use beyond the ASCII subset.
Strings (variable-length): UTF-8 with an explicit uint16_t byte length prefix; not NUL-terminated. Today, content is limited to single-byte characters (ASCII subset) by convention; future header flag(s) MAY indicate extended UTF-8 usage.
Symbols: All security symbols/tickers are fixed-width char[12], uppercase ASCII (A–Z, 0–9, ".", "-") under current convention. Encoded as UTF-8; presently single-byte characters only.
Counts & lengths: All counts and lengths are measured in bytes, not Unicode code points.
Sequence rollover: sequence_number increments by 1 per message and wraps modulo 2³². Receivers SHOULD treat sequence arithmetic modulo 2³² and tolerate modest reordering on multicast.
Deduplication: dedupe_id is 32-bit. Uniqueness is targeted within a small time window; collisions MAY occur. Receivers MAY prefer the first-seen instance and discard subsequent duplicates with the same dedupe_id within that window.

Message Bodies

Headline Message v0.1

struct HeadlineMessage {
  uint8_t  schema_version; // high nibble = major, low nibble = minor (0x01 => v0.1)
  uint8_t  source;       // registry-defined source type
  uint8_t  language;     // uint8 -> registry mapping to ISO 639-1
  uint8_t  ticker_count;
  char     tickers[][12];
  char     headline_text[]; // UTF-8, variable-length to end of message
};

Ticker-tagged headline with UTF-8 text. Delivered immediately and repeatedly over multicast. language is a uint8 registry value that maps to ISO 639-1 codes.

Story Body Fragment v0.1

struct StoryBodyFragment {
  uint8_t  schema_version;     // high nibble = major, low nibble = minor
  uint32_t referenced_sequence; // sequence of the originating Headline message
  uint16_t fragment_index;      // zero-based
  uint16_t fragment_count;      // > 0
  char     fragment_text[];     // UTF-8 variable-length to end of message
};

Multipart UTF-8 content tied to a headline. Serially multicast. TCP/WebSocket fallback in development. Fragments are not required to be equal-sized. Reassembly is by referenced_sequence + (fragment_index, fragment_count).

Someone Said Something Message v0.1

struct SomeoneSaidSomethingMessage {
  uint8_t  schema_version;     // high nibble = major, low nibble = minor
  uint16_t someone_identifier; // registry of tracked figures
  uint8_t  speech_type;        // registry of remark types
};

Alert of statements by key public figures. Signal only; no content.

Someone Said X Message v0.1

struct SomeoneSaidXMessage {
  uint8_t  schema_version; 
  uint16_t someone_identifier;
  uint8_t  speech_type;
  uint8_t  ticker_count;
  char     tickers[][12];
  uint8_t  country_code_count;
  char     country_codes[][2]; // uppercase ISO 3166-1 alpha-2; not NUL-terminated
  char     headline_text[];    // UTF-8
};

Real-time alerts including the (at least partial) statement made by key public figures. Ticker-tagged; country-tagged where applicable. country_codes are uppercase ISO 3166-1 alpha-2.

Disclosure Message v0.1

struct DisclosureMessage {
  uint8_t  schema_version; 
  uint16_t person_id;
  uint8_t  trade_count;
  DisclosureTrade trades[];
};

struct DisclosureTrade {
  uint16_t person_id;          // may repeat for attribution; same as header-level person_id
  uint8_t  account_type;       // enum registry
  uint8_t  asset_type;         // enum registry
  char     underlying_ticker[12];
  uint16_t asset_name_len;     // <= 256 bytes
  char     asset_name[];       // UTF-8, variable, not NUL-terminated
  uint32_t trade_date;         // Unix time, UTC seconds; use 00:00:00 for date-only
  uint8_t  transact_type;      // enum registry
  uint8_t  value_range;        // enum registry
};

Structured congressional disclosures including asset details and transaction types. trade_date uses Unix epoch seconds (UTC). Variable-length strings are length-prefixed and limited to 256 bytes.

Macro Data Message v0.1

struct MacroDataMessage {
  uint8_t  schema_version; 
  uint16_t event_count;
  MacroEvent events[];
};

struct MacroEvent {
  uint64_t event_id;           // release/reference id
  uint16_t indicator_count;
  MacroIndicator indicators[]; // keys are scoped per event type
};

struct MacroIndicator {
  uint8_t key;                 // u8 key per event type
  float   value;               // IEEE-754 binary32, big-endian
};

Macro indicators grouped by event. key is specific to the event type; the same numeric key may be reused in other event types with different meanings. Values are 32-bit floats; units defined by registry.

Index Addition/Deletion Message v0.1

struct IndexAdditionDeletionMessage  {
  uint8_t  schema_version; 
  char    index_name[256];  // UTF-8; NUL-terminated if shorter than field
  uint8_t event_count;
  AdditionDeletionMessage events[];
};

struct AdditionDeletionMessage {
  uint8_t is_addition;      // 1 = addition, 0 = deletion
  char    ticker[12];
};

Bundles multiple add/delete events per index. is_addition is an explicit uint8.

Earnings Message v0.1

struct EarningsMessage {
  uint8_t  schema_version; 
  char     ticker[12];
  uint16_t entry_count;
  EarningsEntry entries[];
};

struct EarningsEntry {
  char     fiscal_period_label[16]; // ASCII label: 2025Q2, 2024H1, 2025M07, 2023, etc.
  OptionalField optional_fields[];  // key-value metrics through message end
};

struct OptionalField {
  uint16_t key;   // registry of metrics (e.g., EPS_GAAP, REV, GUIDE_REV_LOW)
  float    value; // IEEE-754 binary32
};

Flexible, fast-parsing earnings messages. fiscal_period_label is a compact ASCII tag that supports annual (e.g., 2023), half-year (2024H1), quarter (2025Q2), and month (2025M07) reporting.

Schema Versioning

Envelope vs. body: The common header version governs the envelope and transport semantics. Each message body begins with a schema_version (uint8_t).
Encoding: schema_version packs major in the high nibble and minor in the low nibble (e.g., 0x01 → v0.1, 0x21 → v2.1).
Compatibility: Minor bumps are additive only (append optional fields at the end). Major, breaking changes SHOULD use a new message_type.
Receiver guidance: If a body’s schema_version is newer than supported, parse known leading fields and ignore unknown tail bytes using message_length.

Transport Hygiene

Max datagram size: Messages SHOULD be ≤ 1508 bytes to avoid IP fragmentation on common MTUs.
Multicast sequencing: sequence_number is per publisher across all multicast groups. Receivers SHOULD de-duplicate using (publisher_id, sequence_number) and MAY drop messages outside a reasonable reorder window.
Retransmission: The multicast channel does not provide retransmit.
Integrity: UDP checksums exist but are relatively weak (16-bit ones’-complement) and may be elided on IPv4 (checksum 0). Link/NIC offloads can also mask corruption scenarios.
Compression: Not used by default. Future-use flag bits may indicate compressed payloads (e.g., LZ4) along with an uncompressed-length field in the body type that uses it.
Character encoding: All text is UTF-8. Presently, emitters produce only single-byte characters (ASCII subset). Future header flag(s) MAY indicate use of extended UTF-8 or alternative encodings; receivers MUST accept full UTF-8.

Registries & Enums

Unknown enum values MUST be ignored by receivers.

Under Development

Additional formats under development include Transcription and other domain-specific feeds.