Specification: This document reflects a work-in-progress wire format and API. It is subject to change without notice.

Quincy News API & Wire Format

Realtime access via multicast, WebSocket, or physical cross-connect. Designed for ease, 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
WebSocket delivery — cloud-native and globally accessible

Our backbone spans data centers and clouds worldwide.

Common Message Header

Every message begins with this 28-byte header.

MessageHeader

Field	Offset	Size	Type	Description
`schema_version`	0	1	`uint8_t`	See Schema Versioning.
`flags`	1	1	`uint8_t`	See Flags.
`message_type`	2	2	`uint16_t`	Registry below.
`message_length`	4	2	`uint16_t`	Header and body.
`wire_id`	6	2	`uint16_t`	Source wire.
`publisher_id`	8	2	`uint16_t`	Publisher sending to this channel.
`reserved`	10	2	`uint16_t`	Ignore.
`sequence_number`	12	4	`uint32_t`	+1 per message, per publisher, per channel; wraps at 2³².
`content_id`	16	8	`uint64_t`	Source document within `wire_id`; 0 if unavailable.
`source_timestamp_s`	24	4	`uint32_t`	Source document time where available; seconds since epoch, UTC.

message_type (registry)

Value	Message type
0	Heartbeat
2	Headline
3	StoryBodyFragment
4	Disclosure
8	EventIndicators
9	Catalyst

Flags

bit 0 (0x01): restatement or modification of earlier content.
bit 1 (0x02): test message; receivers MUST drop it.
bit 2 (0x04): publisher restarted and sequence_number reset.
bits 3–7: defined per message type or channel. Receivers MUST ignore bits they do not recognize.

Wire Semantics & Conventions

Channel: one stream of messages, delivered as a multicast group or over a TCP connection.
Byte order & packing: Integers are unsigned little-endian. Fields are packed as listed, with no padding.
Strings (fixed-width): UTF-8, NUL-terminated unless the field is full. Bytes after the NUL are padding.
Strings (variable-length): UTF-8, not NUL-terminated; the byte length is in a length field.
Symbols: Fixed-width char[12] in MIC:TICKER form: uppercase ASCII (A–Z, 0–9, ".", "-") with a ":" separator.
Offsets: in bytes from the start of the message, shown where fixed. A field without one follows the previous field.
Lengths: in bytes, not code points.
Enums: receivers MUST ignore unknown values.
Deduplication: the same message can arrive from more than one publisher. A message duplicates one seen recently when its header schema_version, flags, message_type, wire_id, and content_id match, plus fragment_index for Story Body Fragments.

Message Bodies

Heartbeat v0.1

Publisher liveness. No body to parse.

Headline Message v0.1

HeadlineMessage

Field	Offset	Size	Type	Description
`schema_version`	28	1	`uint8_t`
`language_id`	29	1	`uint8_t`	Registry below.
`ticker_count`	30	1	`uint8_t`
`headline_length`	31	2	`uint16_t`
`tickers`	33	Variable	`char[ticker_count][12]`	`MIC:TICKER`
`headline_text`	—	Variable	`char[headline_length]`

Ticker-tagged headline with UTF-8 text.

language_id (registry)

Value	Language	Tag
1	Unknown	—
2	English	en
3	Spanish (Castilian)	es
4	German	de
5	French	fr
6	Hebrew	he
7	Italian	it
8	Portuguese	pt
9	Chinese (Mainland)	zh-cn
10	Chinese (Hong Kong)	zh-hk

Story Body Fragment v0.1 / 2.0

StoryBodyFragmentMessage

Field	Offset	Size	Type	Description
`schema_version`	28	1	`uint8_t`	Encoding profile (below).
`fragment_index`	29	2	`uint16_t`	0-based.
`fragment_count`	31	2	`uint16_t`
`fragment_length`	33	2	`uint16_t`	Uncompressed UTF-8 byte length of this fragment.
`encoded_area`	35	Per profile	`uint8_t[]`	Per profile.

Story text in fragments, reassembled by content_id + (fragment_index, fragment_count). Under 0x01 and 0x20 each fragment decodes on its own. schema_version selects the encoding profile.

Encoding profiles

schema_version	Profile	encoded_area	message_length
`0x01`	Plain UTF-8	`fragment_text`	28 + 7 + `fragment_length`
`0x10`	Zstandard	Not yet available
`0x20`	Reverse Zstandard	`reverse_bytes(zstd_frame(fragment_text) \|\| random_padding)`	1450 (`encoded_area` 1415)

0x20 Reverse Zstandard

The fragment text is compressed into one Zstandard frame, padded with random bytes to fill the 1415-byte encoded area, and byte-reversed. The frame header therefore arrives last, so decoding begins only after the full datagram has arrived. The compressed length is not on the wire; the receiver reads it from the frame.

Example decode:

logical_area  = reverse_bytes(message[35:1450])
frame_length  = ZSTD_findFrameCompressedSize(logical_area, 1415)
fragment_text = zstd_decompress(logical_area[0:frame_length], dictionary_or_none)

Dictionaries

A Zstandard dictionary MAY be assigned to a channel and distributed before use; the frame then carries its dictionary ID. Without one, decode with a plain Zstandard context.

Validation (all profiles)

Reject a fragment when the length is wrong for the profile, the schema version is unsupported, fragment_count is 0, fragment_index ≥ fragment_count, the Zstandard frame is invalid, incomplete, or names a dictionary you do not hold, decompression exceeds your fragment-size limit, the decoded length differs from fragment_length, or the text is not valid UTF-8.

Catalyst Message v0.0

CatalystMessage

Field	Offset	Size	Type	Description
`schema_version`	28	1	`uint8_t`
`document_type`	29	2	`uint16_t`	Within `wire_id`, e.g. 13D for EDGAR.
`entry_count`	31	1	`uint8_t`
`induction_window_bucket`	32	1	`uint8_t`	Expected delay before market reaction; registry below.
`reserved`	33	2	`uint16_t`	Ignore.
`entities`	35	Variable	`QuincyEntityID[entry_count]`

QuincyEntityID

Field	Offset	Size	Type	Description
`quincy_entity_id`	—	8	`uint64_t`	Company.

Flags entities with elevated event intensity that may see abnormal price movement.

induction_window_bucket (registry)

Value	Bucket
0	Unknown
1	Subsecond
2	Seconds
3	More

Raw News v0.1

RawMessage

Field	Offset	Size	Type	Description
`schema_version`	28	1	`uint8_t`
`source_wire`	29	1	`uint8_t`	Third-party source (registry).
`vendor_message`	30	Rest of message	`uint8_t[]`	The source's native message.

Event Indicators v0.1

EventMessage

Field	Offset	Size	Type
`schema_version`	28	1	`uint8_t`
`event_count`	29	1	`uint8_t`
`events`	30	Variable	`Event[event_count]`

Event

Field	Offset	Size	Type	Description
`event_id`	—	4	`uint32_t`	Registry: `https://quincy.news/event_indicator_registry.json`
`indicator_count`	—	1	`uint8_t`
`indicators`	—	Variable	`EventIndicator[indicator_count]`

EventIndicator

Field	Offset	Size	Type	Description
`indicator_id`	—	1	`uint8_t`	Event-specific indicator registry.
`value`	—	1–8	`Per registry`	One of `bool`, `(u)int8/16/32/64`, `float32`, `float64`.

A message may carry several events, typically from the same primary source.

Congressional Trading Disclosure v0.1

DisclosureMessage

Field	Offset	Size	Type	Description
`schema_version`	28	1	`uint8_t`
`someone_id`	29	2	`uint16_t`	Tracked figure. Registry: `https://quincy.news/someone_registry.json`
`trade_count`	31	1	`uint8_t`
`disclosure_trades`	32	Variable	`DisclosureTradeMessage[trade_count]`

DisclosureTradeMessage

Field	Offset	Size	Type	Description
`asset_type`	—	1	`uint8_t`	Registry below.
`underlying_ticker`	—	12	`char[12]`	`MIC:TICKER`
`trade_date`	—	4	`uint32_t`	Seconds since epoch, UTC.
`transact_type`	—	1	`uint8_t`	Registry below.
`value_range`	—	1	`uint8_t`	Registry below.
`asset_name_length`	—	1	`uint8_t`
`description_length`	—	1	`uint8_t`
`asset_name`	—	Variable	`char[asset_name_length]`
`description`	—	Variable	`char[description_length]`

DisclosureMessage Registry

asset_type

Value	Code	Description
0	UK	Unknown
1	4K	401K and Other Non-Federal Retirement Accounts
2	5C	529 College Savings Plan
3	5F	529 Portfolio
4	5P	529 Prepaid Tuition Plan
5	AB	Asset-Backed Securities
6	BA	Bank Accounts, Money Market Accounts and CDs
7	BK	Brokerage Accounts
8	CO	Collectibles
9	CS	Corporate Securities (Bonds and Notes)
10	CT	Cryptocurrency
11	DB	Defined Benefit Pension
12	DO	Debts Owed to the Filer
13	DS	Delaware Statutory Trust
14	EF	Exchange Traded Funds (ETF)
15	EQ	Excepted/Qualified Blind Trust
16	ET	Exchange Traded Notes
17	FA	Farms
18	FE	Foreign Exchange Position (Currency)
19	FN	Fixed Annuity
20	FU	Futures
21	GS	Government Securities and Agency Debt
22	HE	Hedge Funds & Private Equity Funds (EIF)
23	HN	Hedge Funds & Private Equity Funds (non-EIF)
24	IC	Investment Club
25	IH	IRA (Held in Cash)
26	IP	Intellectual Property & Royalties
27	IR	IRA
28	MA	Managed Accounts (e.g., SMA and UMA)
29	MF	Mutual Funds
30	MO	Mineral/Oil/Solar Energy Rights
31	OI	Ownership Interest (Holding Investments)
32	OL	Ownership Interest (Engaged in a Trade or Business)
33	OP	Options
34	OT	Other
35	PE	Pensions
36	PM	Precious Metals
37	PS	Stock (Not Publicly Traded)
38	RE	Real Estate Invest. Trust (REIT)
39	RF	REIT (EIF)
40	RN	REIT (non-EIF)
41	RP	Real Property
42	RS	Restricted Stock Units (RSUs)
43	SA	Stock Appreciation Right
44	ST	Stocks (including ADRs)
45	TR	Trust
46	VA	Variable Annuity
47	VI	Variable Insurance
48	WU	Whole/Universal Insurance

transact_type

Value	Code	Meaning
0	unknown	—
1	P	Purchase
2	S	Sale
3	S (Partial)	Partial sale

value_range

Value	Range (USD)
0	unknown
1	1,001 – 15,000
2	15,001 – 50,000
3	50,001 – 100,000
4	100,001 – 250,000
5	250,001 – 500,000
6	500,001 – 1,000,000
7	1,000,001 – 5,000,000
8	5,000,001 – 25,000,000
9	25,000,001 – 50,000,000
10	50,000,001 +

Schema Versioning

The header and each message body carry their own schema_version.
Major version in the high nibble, minor in the low: 0x01 is v0.1, 0x21 is v2.1.
Minor versions only append fields at the end. For a newer minor version, parse the known fields and skip the rest using message_length.
Major versions may change the layout. Reject a major version you do not support.

Under Development

Additional formats may be introduced behind new message_type values.