Skip to main content
What this stream gives you. Open one HTTP connection and the server keeps it open, pushing each contract’s latest price, every new bid, and every trade as they happen. It uses server-sent events: a browser reads it with EventSource, and any HTTP client can read it line by line.

Request

Send symbols, events, or both; duplicates are removed. A connection can carry up to 200 contracts, counted after events are expanded. Event IDs come from Search with type=events, or from a contract’s eventId. Get Event Contracts lists the contracts an event expands to. An event is expanded once, when you connect: a contract listed under it later is not added until you reconnect.

Events

ForecastEx takes buy orders only. Every order is a bid, for YES or for NO. A bid on one outcome is what the other can be bought at, which is how the best ask is worked out. A : ping comment is sent every 15 seconds to keep idle connections open.

subscribed

events is present only when you asked for events.

unavailable

Sent once for each symbol or event you asked for that is not streamed. Exactly one of symbol and eventId is set. Everything else you asked for streams as usual. Branch on code; message text is not fixed. The event is named unavailable, not error, because EventSource uses error for its own connection errors.

snapshot

The venue reports a contract’s last trade without saying which outcome it was for. The snapshot reads it as the YES price and sets NO to 1.00 minus it. After the first live trade, yes and no come from tagged trades.

Best bids and asks

Pass asks=true to see each outcome’s best bid and what it can be bought at now. A NO bid at q is a YES seller at 1.00 − q, so:
  • Each outcome’s best bid is its highest bid.
  • YES’s best ask is 1.00 minus NO’s best bid.
  • NO’s best ask is 1.00 minus YES’s best bid.
  • bidSize and askSize are the total size of every bid at that price.
The snapshot then carries bid, bidSize, ask, and askSize in place of last and lastSize:
After it, an ask event carries both sides whenever one of the four prices moves:
Each ask replaces the last. It is sent only when a price moves: an order joining or leaving the best price changes only its size and sends nothing, so sizes are as of the last price move. A bid being filled or cancelled is not sent as an event, so ask is the only way to see the prices move when that happens. With asks=true, bid events are not sent. A new bid that moves a best price arrives as an ask, and one below the best changes nothing this stream shows. trade, stats, and gap are sent as usual. A bid is null when nobody bids on that outcome, and an ask is null exactly when nobody bids on the other outcome. This happens on contracts that trade, too: an order that crosses fills at once and never rests. A book with any order still prices both sides. With only YES bids resting at 0.53, YES has a bid of 0.53 and NO an ask of 0.47. Without asks=true, the stream is exactly as described above: bid events, no ask events, and last/lastSize in the snapshot.

bid

A bid is sent when it is placed. Its later fills and cancellation are not sent, so a bid event does not mean the order is still resting.

trade

A match is a YES buyer and a NO buyer, so every match arrives as two trade events with the same tradeId: one for each outcome, at prices that add up to 1.00. Count matches by tradeId, not by event.

stats

Each stats replaces the last. A match usually sends two: volume and notional change with the trade, and open interest follows. A new last price on its own sends no stats, because the trade events already carry it.

Contracts from events

For a contract you subscribed to through events, every snapshot, ask, bid, trade, stats, and gap also carries eventId:

Ordering

  • For each contract, snapshot comes first, and nothing else is sent for that contract before it.
  • After that, bid, trade, stats, and ask arrive in the order the venue sent them, and a match’s two trades come before the stats they moved.
  • Events for different contracts interleave.
If the contract is already being streamed, its snapshot is sent at once. Otherwise it arrives once the venue answers, usually within about a second.

Reconnecting

Events have no IDs and are not replayed. When you reconnect, as EventSource does on its own, you receive a new subscribed and a fresh snapshot for every contract. Bids and trades sent while you were disconnected are lost, but the snapshot’s prices and statistics show where the market is now.

Examples

cURL
Browser

Working with the stream

  • Prices are decimal strings. "0.53", not 0.53. Parse them with a decimal type.
  • A missing value is null, not zero. A null last price means the outcome has not traded, a null bid that nobody is bidding on the outcome, and a null ask that nobody is bidding on the other outcome.
  • Do not put the stream behind a buffering proxy. Events must reach you as they are sent.

Errors

Errors are returned before the stream opens, in the usual error envelope: When anything in the request can be streamed, UNAVAILABLE_SYMBOL, UNKNOWN_EVENT, and NO_LIVE_CONTRACTS are sent as unavailable events on the open stream instead. An unknown symbol is not an error. It never receives a snapshot.