DOCS · API

READ THE INSTRUMENT BY WIRE.

Every endpoint returns JSON with the block number it was read at. Chain integers are decimal strings. Errors are { error: { code, title, message } } with a matching HTTP status. Routes are rate-limited per IP, read-only, and never forward user input as an RPC method.

GET/api/market/:address

Full block-stamped reading for a token address, pool address or ticker: price, reserves, liquidity, depth ladder, impact, verdict, evidence.

/api/market/WETH ↗

GET/api/quote?market=&amount=&side=

Simulate a USD-sized trade against the pool: amountIn, amountOut, averagePrice (fee excluded), effectivePrice, spotPrice, priceImpact, minimumReceived, blockNumber.

/api/quote?market=AAPL&amount=10000&side=BUY ↗

GET/api/compare?markets=a,b,c,d

Up to four readings, each independent with its own block stamp; per-slot errors.

/api/compare?markets=WETH,AAPL ↗

GET/api/markets

The universe: every registry stock token and configured crypto token with a supported pool, list-mode scores.

/api/markets ↗

GET/api/receipt/:address

SVG market receipt of the current reading (shareable, OG-friendly).

/api/receipt/WETH ↗

POST/api/scan { input }

The terminal pipeline with every step recorded (VALIDATING → READING CONTRACT → IDENTIFYING POOL → READING RESERVES → MEASURING DEPTH → CALCULATING IMPACT → PRINTING REPORT).

{"input":"0x…"}

GET/api/receipts/:asset

Receipts other wallets stamped on chain for this asset (ReltRegistry), newest first, read at one block.

/api/receipts/0x0bd7d308f8e1639fab988df18a8011f41eacad73 ↗

GET/api/watchlist/:address

The assets a wallet keeps on chain in ReltRegistry.

/api/watchlist/0x0000000000000000000000000000000000000001 ↗

GET/api/contracts

ReltStock contract status (QuoterV2, ReltRegistry): configured address, bytecode present, identity verified. Add ?payloads=1 for creation bytecode.

/api/contracts ↗

GET/api/token

The $RELT plate: status SOON until RELT_TOKEN_ADDRESS is set, then ERC-20 metadata, pool reading and verdict, live.

/api/token ↗

GET/api/registry

Normalized asset registry (symbol, name, tokenAddress, underlyingAsset, assetType, chain, verified). Identity only.

/api/registry ↗

GET/api/head

Latest block, timestamp, RPC label and latency.

/api/head ↗

GET/api/status

Instrument diagnostics: RPC endpoints, adapters, registry state, active thresholds.

/api/status ↗

MARKET RESPONSE SHAPE

{
  chain: { id, name },
  blockNumber, timestamp, freshness: { ageSec, bucket: FRESH|AGING|STALE, rpcEndpoint },
  token0, token1, asset, quote,
  pool: { address, protocol: UNISWAP_V2|UNISWAP_V3, feeTier, factory, verified },
  price: { usd, inQuote, withheldReason },
  reserves: { asset, quote },
  liquidityUsd, totalLiquidityUsd,
  depth: { impact05, impact1, impact2, impact5, impact10, side: "BUY", status },
  depthDetail: { buy, sell },      // per-level amountIn / usd / OK|PARTIAL|UNAVAILABLE
  impact: { tradeUsd, priceImpactPct, status },
  activity: { windowBlocks, fromBlock, toBlock, swaps, volumeUsd },
  verdict: { verdict, label, score, zone, reasons, components, flags },
  source: { rpcEndpoint, latencyMs, evidence, selectedSourceReason, sources },
  measuredBy: "ReltStock"
}

ADDING A PROTOCOL

Implement MarketAdapter in src/lib/providers/types.ts (discovery specs, block-stamped pool reads, exact-input quote, depth at impact levels) and register it in src/lib/providers/market.ts. Anything without an adapter is reported as UNSUPPORTED MARKET — never approximated. Methodology: /methodology.