# NEWSFEED

The ledger of tokenized shares: what a Robinhood stock token claims to be
worth, and what it actually trades for.

A tokenized share claims to be worth the listed share it tracks. On-chain it
trades at its own price, every hour of the week, including the hours the stock
exchange is dark. NEWSFEED reads every stock token on Robinhood Chain from
2 independent sources (pool, executable; explorer, derived),
takes the median of the sources that agree, reads the listed share from the
exchange feed, and publishes the gap AND how far the sources disagreed.

The universe is discovered from the chain, not typed in: every ERC-20 whose
name ends in "• Robinhood Token". New listings appear on the next discovery
sweep by themselves.

## Endpoints

GET https://www.newsfeed.space/v1/depegs        only tokens genuinely off their listed share, with the error bar
                             ?symbols=AAPL,TSLA and ?limit=N narrow it; the answer says what it was cut to
GET https://www.newsfeed.space/v1/peg           every token, including what was withheld and why
GET https://www.newsfeed.space/v1/peg/AAPL      one token, both sources, the listed share, the gap
GET https://www.newsfeed.space/v1/venues        how each source is behaving
GET https://www.newsfeed.space/v1/health        which sources answered, whether the exchange is open, the house rules
GET https://www.newsfeed.space/v1/opportunities the findings shaped to act on: direction, the pool, token and quote addresses, depth, volume
                             ?symbols=AAPL,TSLA and ?limit=N narrow it, same as /v1/depegs
GET https://www.newsfeed.space/v1/wire?since=ms the wire as a feed: every token that newly cleared its error bar after since (10-minute buckets)
GET https://www.newsfeed.space/v1/peg/AAPL/history  a reading every 10 minutes for 7 days, each with its gap and error bar
GET https://www.newsfeed.space/v1/access/wallet holder access: the token, the minimum balance, the exact message to sign
POST https://www.newsfeed.space/v1/access/wallet {"address","timestamp","signature"} → a full-access key minted for the wallet
GET https://www.newsfeed.space/v1/openapi.json  machine-readable contract
GET https://www.newsfeed.space/v1/access        the tiers, and how many have asked for full access
POST https://www.newsfeed.space/v1/access       request full access: {"via":"x"|"github","handle":"...","note":"..."}

Fast lane for keyed calls: send the key as x-newsfeed-key: <key> instead of Authorization and the
answer is kept at the edge for that key alone (Vary), so a second call within thirty seconds
is served from the edge near you; Authorization: Bearer still works and is never cached.
server-timing on every answer shows what the instance spent: board (memory or computed) and body.

Manners on the wire: every answer carries an ETag — send it back as If-None-Match and an
unchanged sweep is a 304 with no body. The public tier allows 120 calls a minute per address
and says so in x-ratelimit-* headers; keyed calls are not limited. context.ageSeconds on every
envelope is how old the sweep behind it is.

CORS is open. Token sources are swept every 90s; the listed share every 10 min.

## Tiers

Without a key you are on the PREVIEW tier. It exists to prove the instrument
works, not to be the product:

  in full        AAPL, TSLA, NVDA, SPY — share, token price, gap, error bar, both sources
  verdict only   every other token — "significant" and venueCount survive; the
                 numbers are withheld and the reading carries locked: true

Every response says which tier served it in the "access" field. FULL access
adds the withheld numbers on every token. Request it with an X or GitHub handle
(POST /v1/access, or the form on the site); a key is sent back on that platform
and used as  Authorization: Bearer <key>.

## The one thing to understand before using this

Most "mispricing" alerts are bad quotes, not mispricings.

A thin pool and a lagging explorer rate will disagree with each other by more
than the gap being claimed. NEWSFEED publishes the disagreement as
uncertaintyPct and refuses to call a gap a finding when it is smaller than
that. It also refuses gaps wider than 6%: a token 6% from its share is not
an edge, it is a dead market or a corporate event the token has not priced.
Those are shown with suspect: true and never published on /v1/depegs.

  share           the listed share's last regular-session price
  price           the token's consensus price
  deviationPct    (price − share) / share, percent; negative is under
  uncertaintyPct  half the spread of the agreeing sources — the error bar
  significant     true only when |deviationPct| > uncertaintyPct AND > 0.25%,
                  from two or more sources, and not suspect
  suspect         |deviationPct| > 6%

A token priced by a single source has NO uncertainty figure, because one quote
cannot be corroborated. Those readings are unverified.

When the exchange is dark the share price is the last close; every gap is
measured against it. That is the point, not a defect: the token market keeps
pricing news the exchange has not opened to absorb yet.

## Not measured

Tokens with no listed share (private companies, delisted names) carry
share: null and no deviation. Nothing here is financial advice.