Prices

Every quote and every catalogue row says which of the two you are holding. Read it: a reference-priced quote is an estimate wearing a price's clothes, and you are entitled to know which one you have.

How a side is priced

• Buying YES crosses the YES ask. Selling YES hits the YES bid.
• Where a source publishes a NO book directly, that book is used. Where it does not, NO is mirrored from YES: a NO ask is 1 − (YES bid), which is arithmetically exact for a binary contract.
• A crossed book, bid at or above ask, is discarded on both sides and the quote falls back to the reference. Bad data that looks like a gift is exactly what a router would otherwise pick every time.
• A spread wider than the configured maximum (0.2 by default) is treated as no usable two-way price: an illiquid book's midpoint is noise, not a probability.
• 0 and 1 are settled, not tradeable. Neither is ever published as a price.

On a catalogue outcome, executableYesCents and executableNoCents are null whenever the book publishes no usable side, and so are execution.buyYes and execution.buyNo on the same contract in the live price stream. That null is a value, not a gap in the response.

"yesCents": 63.4,              // reference: a midpoint
"noCents": 37.2,
"executableYesCents": 65.1,    // what a YES buy costs
"executableNoCents": null,     // no usable side: show no price
"priceBasis": "midpoint"

"probability": 0.634,
"execution": { "buyYes": 0.651, "buyNo": null, "basis": "book" },
"tradeable": true

• On the stream, execution.basis is book when at least one side came off a real two-way price, and reference when neither did. Read the per-side value for what to display, and the basis for how much to trust the row.
• A quote is the authority, not the catalogue. The catalogue tells you whether to offer a control; the quote tells you what the trade costs. Never charge from a catalogue price.
• An outcome with no executable side can still be shown as a market with a probability. What it cannot be shown with is a price or a buy button.

Catalogue prices are decimals between 0 and 1. The cent figures, yesCents and noCents, are rounded to the tenth of a cent, which is the finest tick any upstream actually uses. 63.4 is a legitimate value and so is 0.3.

• Carry prices at the precision you receive them, all the way to display. Round for the player's eye only, at the last step, and never before a calculation.
• Contract counts are returned rounded to four decimal places for transport. The stored quote keeps full precision and is what the fill is checked against: so do not recompute contracts from a rounded figure and expect a match.
• Money amounts are cents-exact. On a quote the stake is rounded to the cent once, the fee rounds up to the cent and potentialPayout rounds down to the cent. The settlement credit is computed separately, from the contracts actually held, and also rounds down to the cent, so it matches the quoted payout for the same contracts. Prices are not money, and rounding them the same way is the error this section exists to prevent.
• Never store a price as an integer number of cents. It is the same bug as rounding, held for longer.

Prices carry an age, and the age decides what may be traded. Thresholds depend on the feed and on the kind of contract: a streamed price 60 seconds old means the socket broke while a polled price 60 seconds old is simply normal, and a five-minute contract or a fixture being played moves too fast for either.

The live tier applies to a fixture that has kicked off and to any market within 15 minutes of its close. The five-minute column applies to the recurring five-minute crypto contracts. Where a price will not be confirmed against a fresh book when the order is submitted, each band takes the cap of the band below it: fresh is capped at the aging figure, and aging and stale at the stale figure.

• A missing timestamp is treated as suspended, not fresh. An unknown age is precisely the case where the price could be hours old.
• The gate runs on the server, at quote time and again at order time. A quote that was fresh when issued can go stale inside its own lifetime.
• Every quote returns its own verdict in freshness. Render that rather than recomputing your own: the two disagreeing is the bug the field exists to prevent.

"freshness": { "level": "fresh", "ageSeconds": 5, "feed": "websocket" }

An embedded surface does not have to poll, and does not have to be given a server to poll from. GET /api/v1/stream/prices?contracts=ctr_…,ctr_… is a Server-Sent Event stream: one connection per page, however many contracts it watches, pushing when a price moves rather than on a timer.

const feed = new EventSource(
  '/api/v1/stream/prices?contracts=' + ids.join(','),
);

// Everything you hold. Safe to replace state with.
feed.addEventListener('snapshot', (e) => replace(JSON.parse(e.data).quotes));
// Only what changed. Patch, never replace.
feed.addEventListener('update',   (e) => patch(JSON.parse(e.data).quotes));
// The FEED went quiet, as opposed to one price being old.
feed.addEventListener('status',   (e) => setFeedStale(JSON.parse(e.data).stale));

• The fan-out is Parity's. A thousand browsers watching one contract cost one upstream venue subscription, not a thousand. There is nothing to protect by proxying this behind your own server.
• Reconnection is the browser's. EventSource backs off and replays Last-Event-ID on its own (the stream asks for a 3-second retry). The first frame on every connection is hello. When the resume can be honoured, hello.gap is false and an update follows with only what changed; when it cannot, hello.gap is true and a full snapshot follows, which replaces your state.
• Every frame, and what it carries. hello: what you are subscribed to, what was refused and why (unknown, limit, capacity, not_offered), the per-connection limit (128 contracts by default) and heartbeatMs. snapshot and update: quotes. heartbeat (every 15 seconds by default): the feed's age and whether it has gone quiet. status: the feed went stale or recovered. revoked: contracts withdrawn from a live connection. pulse: recent trade activity for animation, sent without an id: and never replayed. error: { code, message }.
• Each quote is { contractId, status, probability, yes, no, execution: { buyYes, buyNo, basis }, asOf, ageSeconds, freshness, tradeable, rev }, with prices as fractions from 0 to 1, not cents, and freshness one of fresh, aging, stale, suspended.
• Offering filter needs a header. An embed session applies your offering policy when sent as Authorization: Embed <token>. A browser's native EventSource cannot set headers, and a token in the query string is refused, so use a fetch-based event-stream reader when you need the filter. With no credential the connection serves the unrestricted public catalogue.
• No API key, on purpose. A browser cannot hold one. Every frame is built from opaque ctr_… ids, normalised prices and an age: no venue is named, no venue id is published, nothing is user-specific. Where an embed session identifies your account, your offering policy still filters what that connection receives.
• A price that stops ticking does not stay looking live. Each quote carries freshness and tradeable, and a frame arrives when a price crosses a band even though nothing new came in. tradeable: false is the platform saying it will not quote that contract right now. The price is still sent, because the last known price is real information, but it is sent labelled.

Two independent levers, deliberately not folded together. An edge is hidden in the price; a fee is an explicit charge a player can see.

stake         50.00
− fee          0.60   (120 bps, rounded up to the cent)
= wagered     49.40
÷ price        0.72   (executionPrice)
= contracts   68.6111
× $1.00 each
= payout      68.61   (quoted: rounded DOWN to the cent)
− stake       50.00
= profit      18.61   (measured against the FULL stake)

• The fee rounds up to the cent and the QUOTED payout rounds down, so the figure a customer is shown is never more than they will receive. The SETTLEMENT credit is rounded down to the cent the same way, from the contracts actually held: 14.529411764705882 contracts credit $14.52, which is the payout a quote for those contracts shows. Book what the settlement instructs; do not recompute it.
• Profit is measured against the full stake, because that is what left the player's balance.
• The platform fee and house edge above are defaults. Your own rate is set in your commercial terms, and every quote echoes the rate it was struck at in platformFeeBps and commercialTerms.
• venueFee is null (with venueFeeKnown: false), not 0, when the execution fee is not being priced into your quotes: writing zero would assert a fact Parity does not have. Where it is priced in, the rate is taken per contract (the catalogue publishes it as venueFeeRate), venueFee carries the amount and venueFeeKnown is true. Either way the quote is the figure to show.