Add rh-stockpair-oracle: pricing for stock-paired pools on Robinhood Chain

[MeMikko]

On Robinhood Chain, launchpads pair new tokens against tokenized equities rather than against ETH. That makes the quote asset something whose price moves on a market with opening hours, splits and dividends — and nothing published reads those pools and says what a token is actually worth in dollars, or how far a pool has drifted from the equity's oracle price while the underlying market is shut.

Live at oracle.sb4s.xyz, answering on Farcaster as @vates.
Source: https://github.com/MeMikko/rh-stockpair-oracle

What it does

Route	Returns
GET /quote	implied USD, depth, quoter-simulated price impact, Chainlink deviation, market hours. Takes a v4 poolId or a v3 pool address
POST /prepare-swap	unsigned calldata with a min-out from the on-chain quoter. v4 and v3 both: UniversalRouter + Permit2 for v4, the v3 router with one scoped ERC-20 approval for v3
GET /gas	chain 4663 gas, split into L2 and L1-data components
GET /corporate-actions	upcoming splits and dividends joined to the pools each one reprices
GET /price?symbol=	a stock's own Chainlink price, or 404 with the reason where no feed exists
GET /pools?symbol= · GET /volume	pool counts by protocol plus the identifiers to quote, ordered by measured 24h swaps; 24h volume with its measurement window
POST /ask	free-text question, structured answer with facts and a reproduce call

It never signs, broadcasts, or holds funds.

Two things worth a reviewer's attention

It indexes Uniswap v3 as well as v4. Measured over 24h, v3 carries ~36% of stock-paired volume, and four of the five largest stock-paired pools by volume are v3. NVDA''s busiest pool is a v3 pool with 256,303 swaps in the measured window, ahead of all 9,942 v4 NVDA pools. An index covering v4 alone misses that — which is what every other RH data source does today.

deviation: null is normal and never means zero. 159 of 194 stock tokens have no Chainlink feed, so for those a deviation is unknowable rather than absent. The response says so with an explicit deviationReason instead of substituting a pool''s implied price — which is a price for the other token in that pool, not for the stock.

Verifiability

Every /ask answer carries the facts behind it and a reproduce field naming a different route that returns the same figure independently, so a caller can check rather than trust:

{ "answer": "10394 indexed pools on Robinhood Chain quote NVDA (9942 on Uniswap v4, 452 on v3).",
  "facts": { "v4Pools": 9942, "v3Pools": 452, "totalPools": 10394 },
  "reproduce": "GET /pools?symbol=NVDA" }
GET /.well-known/agent.json describes every endpoint, the access methods and the known limits in machine-readable form — also returned from GET / with Accept: application/json, and advertised in a Link: rel="service-desc" header.

Access
Billing is on as of 2026-09-03. $0.02 per priced call, one figure for every priced route; /health and /coverage are free and stay free. Every response publishes x-oracle-price-usd, x-oracle-charged-usd and x-oracle-pricing — read them rather than hardcoding a price.

Four ways to pay, and GET /x402/supported says which this deployment honours right now:

Bankr''s x402 gateway — https://x402.bankr.bot/0x4b19ee2a3de2521a3adc901989944c209c0a60ea/vates/<route>. Same routes under the same paths, same responses. It prices its whole path space, so call /health and /coverage at the origin where they are free.
Prepaid credit — one USDC transfer on Base, then POST /x402/topup. Any amount, no minimum.
Scheme exact — the published x402 protocol, advertised only when a facilitator that actually settles it on this network is configured. The origin asks /supported rather than assuming, so the scheme is honestly absent rather than promised and refused. exactSettlement.advertised says which it is today.
Wallet-signature session, and a $5.99/30-day pro tier that also gets direct answers when @vates is tagged.
Known limits, stated rather than left to be found
Multi-hop swaps are unsupported. RH''s UniversalRouter ExactInputParams carries a field upstream v4-periphery does not have; it was empty in all 14 live samples decoded, so its type cannot be determined and guessing it would emit calldata that reverts.
Which v3 router is deployed is read off the chain (factoryV2()), never assumed — the two variants'' structs differ so their selectors differ. If that read fails the route answers 503 rather than emitting half-correct calldata.
No push alerts yet — corporate actions and gas are polled.
Volume is a rolling 24h figure refreshed every 6h, not live; GET /volume reports measuredSecondsAgo.
An independent agent ran the full surface twice against the live deployment and verified the reproduce chain end to end.

🤖 Generated with [Claude Code](https://claude.com/claude-code)
'@ | Set-Content -Path pr-body.md -Encoding utf8