FOUS — Freedom On US Stocks（链上美股）

零 API key 的链上美股代币化资产行情 / 持仓 / 交易系统。查看 Ondo Global Markets 等美股代币（TSLAon、QQQon…）的价格、K线，通过区块链直接查询任意地址的持仓与交易，并支持 Uniswap V4/V3 链上兑换。全程不依赖 ondo.finance 域名（规避地区屏蔽），数据全部来自公共区块链基础设施（Chainlink、DEX 池、GeckoTerminal、Blockscout、CoinGecko、DefiLlama）。

English version: README.en.md

特性

• 零 API key：价格与行情全部来自公共基础设施，无需注册任何付费或免费 key。
• 多源容错定价：快照以 DefiLlama 批量报价为主源，池价重报价带 ±20% 熔断拦截操纵/失效池；实时报价走 Chainlink → DEX 池价 → CoinGecko 单币兜底。
• K线：GeckoTerminal OHLCV 为权威历史源，Binance 补充成交量，尾部 swap 聚合保证秒级新鲜度。
• 实时：价格快照每 5s 经 WebSocket（/ws）推送最新 tick。
• 持仓与地址史：RPC balanceOf 直查估值；ETH 走 Blockscout 免 key API，BSC 走本地累积索引。
• 链上交易：Uniswap V4（Universal Router + Permit2）为主，V3 为兜底，浏览器端 wagmi 执行；权限代币（Ondo KYC）缺权限时阻断并引导 KYC。

架构

数据平面（零 API key）

价格(快照)  DefiLlama 批量报价(主) → 池价重报价(±20%熔断) → 兜底最新快照
价格(实时)  Chainlink 喂价(ETH权益) → DEX 池价 → CoinGecko 单币
K线        GeckoTerminal OHLCV(权威) + Binance 补量 + 尾部 swap 聚合(秒级新鲜度)
实时        价格快照每 5s → WebSocket(/ws) 推送最新 tick
持仓        RPC balanceOf 直查 × 当前价估值
地址史      ETH: Blockscout 免key API / BSC: 本地累积索引
交易        Uniswap V4(Universal Router+Permit2) 主 / V3 兜底, 浏览器端 wagmi 执行

包结构（依赖方向）

shared ← market ← tokenlist ← indexer ← api ← web

• packages/shared 链配置 · ABI · Postgres schema/迁移
• packages/market RPC 客户端(健康记分降级) · 定价引擎 · GeckoTerminal/DefiLlama/CoinGecko 客户端
• packages/tokenlist 代币注册表(Etherscan/BscScan 核验地址)
• packages/indexer 调度器任务: 链上扫描 / K线刷新 / 价格快照 / 池发现 / 回填
• apps/api Hono REST + WebSocket (:8787)
• apps/web Next.js 15 · lightweight-charts v5 · wagmi v2

系统仅运行生产环境（ETH 主网 + BSC 主网），无测试网模式。

代币注册表

• packages/tokenlist 的 PROD_TOKENS 经 syncTokens() 在 api/indexer 启动时写入 tokens 表（表为空则关联查询全失败）。
• 启动时常驻同步两份官方列表（GitHub）：Ondo Global Markets（全部 permissioned: true，需 KYC）与 xStocks（Backed，全部 permissioned: false）。

索引器任务（调度器）

任务	周期	作用
scan-swaps / scan-transfers / scan-v3-swaps	8s / 12s / 15s	实时摄取 V4/V3 Swap 与 ERC20 Transfer（V4 经 tx.from 归属钱包）
discover-pools / resolve-pending-pools / scan-initializes	1h / 5m / 15m	DEX 池发现（DexScreener→工厂→GT）与权限 GM 池初始化扫描
rollup-candles	1m	1h→4h→1d K线层级滚动
snapshot-prices	5m	DefiLlama 批量报价 + 池价重报价（±20% 熔断，失效池冷却 1h）
gt-fast / gt-slow / binance-candles	5m / 30m / 20m	GeckoTerminal K线刷新（1h / 4h+1d）+ Binance 补量
reset-rpc-health / retention	10m / 1h	RPC 健康重置 / 历史数据保留清理

一次性脚本（pnpm --filter @fous/indexer <name>）：discover、backfill、ondoList、ondoPools、token:set-active、token:meta、cleanupCandles。

快速开始

方式一：Docker 一键部署（推荐）

cp .env.example .env          # 按需填写 RPC / API key（均可留空用公共默认值）
docker compose up -d          # 起 postgres + redis + api + indexer + web + 初始化

• 访问 Web: http://localhost:3000 ，API: http://localhost:8787
• init 服务会一次性执行池发现 + K线回填后退出；可随时 docker compose run --rm init 重跑。
• 仅起基础设施（本地跑应用）：pnpm db:up（docker compose up -d postgres redis）
• 查看日志：docker compose logs -f api

方式二：本地开发

pnpm install
pnpm db:up                    # docker 起 postgres + redis
cp .env.example .env
pnpm db:migrate               # 应用 SCHEMA_SQL（幂等）
pnpm --filter @fous/indexer discover   # 解析 DEX 池
pnpm --filter @fous/indexer backfill   # 首次回填 K线历史(GeckoTerminal)
pnpm dev                      # API(:8787) + Web(:3000)

生产常驻：pnpm indexer 启动索引器（ETH + BSC 主网）。

验证门禁：pnpm -r typecheck 是唯一的构建校验；pnpm --filter @fous/web build 是唯一真正的构建（Next.js）。

Web 功能

• 行情页 /：代币表格，支持搜索、类型/分类筛选、分页、排序；标注数据来源（Chainlink/Pool/CoinGecko/DefiLlama/Dexscreener/Candle）。
• 持仓页 /portfolio：连接钱包（wagmi），展示总估值、原生币、持仓明细（余额/价格/涨跌/市值）。
• 代币详情 /token/[chainId]/[address]：实时价 tick、K线图（1h/4h/1d）、近期成交、交易面板（浏览器端执行 swap）、CSV 导出。
• UI 文本为中文（i18n 默认 zh-CN），API 调用经 TanStack React Query。

配置（.env）

变量	说明
DATABASE_URL / REDIS_URL	Postgres / Redis 连接（Docker 内已自动改写为服务名）
ETH_RPC_URL / BSC_RPC_URL	可选，留空用公共节点；*_RPC_URL 可覆盖
ALCHEMY_KEY	可选付费 RPC，与公共节点轮换
API_PORT / WEB_ORIGIN	API 端口 / CORS 来源（默认 8787 / http://localhost:3000）
RATE_LIMIT_WINDOW / RATE_LIMIT_MAX	单 IP 限流窗口(秒) / 次数
INDEXER_START_BLOCK_ETH / _BSC	索引器首次回溯起始块
UNISWAP_API_KEY	可选，Uniswap Trade API（服务端代理，不暴露浏览器）
NEXT_PUBLIC_API_URL / API_PROXY_TARGET	Web 代理目标（Docker 内默认 http://api:8787）

API 摘要

说明：只读端点 candles / trades / quant / address-history / icon 免鉴权；tokens / price / portfolio / dex/* 及 WS /ws 需要 Auth.js 会话。

端点	说明
GET /api/tokens	注册表 + 最新价 + 24h 涨跌 + 权益价与价差 + 成交量
GET /api/price/:chainId/:address	实时报价（Chainlink→池价→CoinGecko，Redis 缓存 5s）
POST /api/price/snapshot	触发（批量）价格快照（运维便利）
GET /api/candles?chainId&address&interval&limit	OHLCV(USD)，interval∈{1h,4h,1d}
GET /api/candles/trades/recent	近期 swap 成交带（来自 swaps 表）
GET /api/portfolio/:chainId/:address	链上余额 × 实时估值
GET /api/trades/:chainId/:address	交易史（swaps+transfers）+ FIFO 盈亏
GET /api/quant/ohlcv.csv?...	量化 CSV 导出（回测用）
GET /api/quant/symbols	机器可读符号列表（含 K线数量）
GET /api/address-history/:chainId/:address	任意地址转账史（ETH 走 Blockscout）
GET /api/icon/:chain/:address	Ondo GM 代币 logo 同源字节代理
WS /ws	每 5s 推送最新价 tick
GET /api/dex/route/:chain/:token	解析 + 探测兑换路由（V4 优先）
POST /api/dex/quote	报价（±20% 偏离熔断，Uniswap Trade API 代理）
GET /api/dex/state/:chain/:token/:wallet	兑换状态（含 universalRouter/permit2/poolManager）
GET /api/dex/permission/:chain/:token/:wallet	KYC 权限校验（权限代币）

DEX 交易

• V4 优先 / V3 兜底：ETH 与 BSC 均走 Uniswap V4（Universal Router + Permit2）；仅当无可用 V4 稳定币池时回退 V3（QuoterV2 报价，客户端直接 approve + exactInputSingle，无 Permit2）。
• 稳定币结算：优先 USDC，代币无 USDC 池时自动回退 USDT；均无则走 V3 稳定币报价池。无 V2 / UniswapX / 聚合器 / 限价单。
• 客户端构建：@uniswap/v4-sdk V4Planner（SWAP_EXACT_IN_SINGLE + settle/take）包进 @uniswap/universal-router-sdk RoutePlanner，仅单跳（多跳被 tradeReasonNoWorkingRoute 拦截）。Permit2 approve 的 expiration 为 number（uint48），非 bigint。
• 权限代币：tokens.permissioned=true 时，/state 与 /permission 调用 checkPermission（探测 ChainConfig.permission.registry，占位 0x0…0 走 transfer(wallet,wallet,1n) 模拟；revert=无权限）。无权限时交易面板阻断并引导 KYC（ondo.finance/global-markets）。
• 熔断：报价相对最新快照偏离 ±20% 即拒绝（BSC 上失效/操纵池报价异常），垃圾报价池默认不可路由。
• 浏览器不导入 @fous/shared/chains（该模块经 env.ts 引入 node:fs，须保持服务端专用）。

设计取舍

• 零 key：全部公共资源；日后可一行接入 Etherscan V2 / HyperSync 升级。
• 定价多源容错：DefiLlama 为主源（按地址批量、免 key、~300/min），Chainlink 覆盖权益类，池价重报价带 ±20% 熔断拦截操纵/失效池，CoinGecko 仅作单币兜底。
• K线双源：GT 为权威历史；Binance 补量；尾部 swap 聚合保证秒级新鲜度并作为量化校准。
• 尾部追踪：放弃深度历史扫描（公共 RPC 限制），历史由 GT 覆盖，实时只扫小范围。
• BSC 地址史：无免 key 数据源，依赖本地累积；ETH 无此限制。
• 交易：V4 优先、V3 兜底；权限代币（Ondo KYC）缺权限时阻断并引导 KYC。

免责声明

仅供技术研究。代币化股票存在合规与对手方风险，不构成投资建议。