How Surge works

In one paragraph

Surge reads three public sources and puts them side by side: Robinhood's list of official stock tokens (to tell real tokens from copycats), Robinhood's and Chainlink's prices (to compute a fair price per token, dividends included), and the Uniswap v4 pools on Robinhood Chain (to see what you would actually pay or receive). The difference between a pool's price and the fair price is what the screens call “vs fair”. If you choose to trade, Surge writes that fair price minus your limit into the transaction as a protected minimum, so a bad fill cancels itself. Below, the same thing in the vocabulary used by the API and the code: the fair price is the reference, the distance from it is the list, and your limit is the band.

1. Identity: the registry is the source of truth

Robinhood publishes the list of Stock Tokens at api.robinhood.com/rhj/assets. Surge reads it server-side (the endpoint has no CORS), validates the shape, and keeps a five-minute cache with a one-hour stale-if-error fallback. A ticker resolves to the address in that list, and only that address. When you verify an arbitrary address, Surge first checks the registry; if it is absent, it reads the contract's symbol() and name() and reports lookalike when the symbol (with decorations like $, x, w or -RH stripped) matches a canonical ticker or the name invokes “Robinhood”. Anything else is unknown — Surge has no opinion about tokens that are not stock tokens.

2. Value: quote × multiplier, cross-checked with Chainlink

Stock Tokens implement ERC-8056. Dividends and splits update uiMultiplier() (18-decimal fixed point); balances never change. One token represents uiMultiplier / 1e18 underlying shares.

• Robinhood quote. /rhj/prices/{symbol} returns bid and ask per underlying share, not multiplier-adjusted. Surge computes mid = (bid + ask) / 2 and tokenPrice = mid × uiMultiplier, using the multiplier read on-chain (registry value as fallback, flagged as degraded).
• Chainlink feed. Some tokens have a Chainlink feed named Robinhood <TICKER> / USD (8 decimals, 24h heartbeat, 0.5% deviation). Per Robinhood's docs the feed price already includes the multiplier, so it is compared to tokenPrice directly.

Freshness

Selection. The reference is the fresh Robinhood price when available; otherwise the fresh Chainlink price; otherwise the most recently updated of the two, marked stale and never used to guard; otherwise unknown. When both are fresh and disagree by more than 2%, the card flags divergence and the guard refuses.

3. Session calendar

Computed in America/New_York: regular 09:30–16:00, extended 04:00–09:30 and 16:00–20:00, overnight 20:00–04:00 from Sunday 20:00 to Friday 20:00, closed otherwise and on NYSE holidays (2026 calendar embedded; verify yearly). The session is informational and drives the Chainlink freshness rule; it never blocks reads.

4. Pools and executable prices

Surge enumerates the hookless Uniswap v4 pools for token/USDG and token/WETH across the 0.01%, 0.05%, 0.30% and 1.00% tiers, reads liquidity from StateView and quotes each USDG pool with V4Quoter.quoteExactInputSingle for the selected size (100, 1,000 or 10,000 USDG): a buy with that much USDG, and a sell of the token amount that size represents at the reference. Executable price = amount of quote asset per token. WETH pools are shown for depth only. Hooked pools and v3 pools are not scanned yet.

List = (executable − reference) / reference, in signed basis points. Negative means below the reference.

5. The guarded swap

For a sell of amountIn tokens, minimum output = amountIn × reference × (1 − band) in USDG. For a buy with amountIn USDG, minimum output = amountIn ÷ (reference × (1 + band)) in tokens. The best pool inside the band is chosen; if none is, Surge refuses with a specific code (halted, paused, reference_unknown, reference_stale, reference_divergent, no_liquidity, outside_band).

The transaction is a single call to the Uniswap Universal Router at 0x8876789976decbfcbbbe364623c63652db8c0904: execute(commands, inputs, deadline) with command V4_SWAP and actions SWAP_EXACT_IN_SINGLE, SETTLE_ALL, TAKE_ALL, plus a deadline 120 seconds after planning. Input tokens are pulled through Permit2, so the first swap needs an ERC-20 approval to Permit2 and a Permit2 approval for the router (30 days, capped at the amount). Before the wallet opens, the call is simulated with eth_call; the plan is re-computed at that moment so the minimum reflects the freshest reference. If the pool cannot deliver the minimum when mined, the router reverts with V4TooLittleReceived and nothing is traded.

6. Provenance and honesty rules

• Every API response lists its sources (with URLs, timestamps, block numbers) and a degraded array naming what could not be read.
• “—” means unknown. Zero is only shown when the chain says zero.
• Nothing is invented: no users, no volumes, no partners, no yields.

7. What is live and what is planned

“Live” means shipped in this repository and working against Robinhood Chain reads today. Everything else is planned and gated as stated; nothing planned is presented as existing anywhere on the site.

• Verification, Fair-Value Card, Portfolio, Public API

  Live

  Registry + on-chain checks, references with freshness, pools per size, ERC-8056-aware holdings, CORS JSON with provenance.

• Guarded swap on Uniswap v4 (USDG-quoted, hookless pools)

  Live

  Universal Router transaction with fair-value minimum output; Permit2 approvals; refusal reasons.

  Gate: Encoding proven on a mainnet fork (sell, buy, revert outside band, expired deadline). A mainnet transaction from a funded wallet is the final confirmation.

• Corporate-action calendar

  Live

  One page and one endpoint for every scheduled and recent dividend or split across the registry, with the estimated multiplier change.

• Alerts

  Planned

  Stale feed, multiplier effective, list beyond band — delivered by webhook or Telegram.

  Gate: Needs a delivery channel and an operator budget; the data endpoints exist.

• Uniswap v3 and hooked v4 venues

  Planned

  Add v3 QuoterV2 and hook-aware pool discovery so the gauge sees the whole market.

  Gate: Hook pools need per-hook safety rules before they can be ranked.

• On-chain Surge Registry + SURGE governance

  Planned

  Canonical list, feed map and policy on-chain, changed by timelocked token vote. Contracts drafted and tested here.

  Gate: Independent audit before any deployment.

• Guard-fee router

  Planned

  A thin router that takes a capped fee from routing surplus (never from principal), discounted in SURGE.

  Gate: Only after the registry is live and the router is audited.

Read the API reference or the token design.