# Meme-Quant Swarm

> Web4 迷你币 AI 智能体分身微支付交易系统 (x402 V2 / ERC-8004 / EIP-712 Intent)
> 版本 2.0.0 · 协议版本 0.2.9 · 网络 base · 结算资产 USDC

## 系统简介

Meme-Quant Swarm 是一个由五个 AI Agent 分身（Scout 侦察兵 / Profiler 侧写师 /
Game Theory 博弈师 / Execution 执行官 / Risk 风控与财务）组成的交易蜂群。
每个 Agent 拥有独立的 ERC-8004 链上护照（tokenId 8001-8005）与 x402 预算命名空间，
通过 x402 V2 微支付按次购买外部数据（貔貅审计 0.05 USDC / 叙事热度 0.02 USDC /
聪明钱画像 0.1 USDC），博弈论推演后生成 TradeIntent（EIP-712 签名），
经统一链适配层（EVM flashbots / Solana jito 多路由 / AppChain 私有排序器）执行。

安全护栏（白皮书第六节第 3 款）：
- 金丝雀模式（S1）：单笔硬顶 50 USDC，日亏损硬顶 100 USDC；正式环境 500/1000
- 断路器：日回撤 ≥5% 或连亏 ≥5 笔 → 熔断（halt_all）；预算耗尽 → local_cache 降级
- 防貔貅：staticcall 模拟失败直接拦截；卖出税率 >10% 拒绝交易
- 原子滑点保底：amountOut < minAmountOut → 整笔 revert，MEV 无利可图

## 付费 API（x402 V2，millionths of USDC）

- POST /api/v1/meme/audit        {tokenAddress}  → 50000 (0.05 USDC)  Meme Token Deep Audit
- POST /api/v1/meme/sentiment    {tokenAddress}  → 20000 (0.02 USDC)  Social Sentiment Score
- POST /api/v1/wallet/profile    {tokenAddress}  → 100000 (0.1 USDC)  Smart Money Profiling

鉴权方式：
1. Authorization: Bearer <session token>   （POST /api/v1/x402/session/init {role} 签发，30 分钟有效，角色预算隔离）
2. x-payment: {"scheme":"exact","nonce":"<uuid>","amount":50000,"signature":"0x..."}  （单次 exact 支付）
3. 无凭证 → 402 返回 X402Challenge（含 exact + session 双方案）

## 免费 API

- GET  /api/v1/swarm/status                          Dashboard 聚合状态（3s 轮询）
- POST /api/v1/swarm/tick                            运行一个完整 Swarm 周期
- GET  /api/v1/risk                                  风控指标快照
- POST /api/v1/risk {action:kill|resume|reset_day|toggle_canary|recover}
- GET  /api/v1/signals?limit=50                      信号列表
- GET  /api/v1/ledger/trace/[signalId]               单信号全生命周期追溯
- GET  /api/v1/trust/registry                        ERC-8004 注册表（护照/数据源声誉）
- POST /api/v1/backtest                              参数化回测沙盒（纯内存模拟，不写 Ledger）
  {cycles:20-500, initialCapital:100-1000000, strategyBias:-0.1~0.1, mevHostility:0-1}
  → equityCurve[] + summary{totalReturnPct, maxDrawdownPct, winRatePct, honeypotBlocked, mevReverts, sharpeLike, verdict}
- GET  /api/v1/export/ledger                         全生命周期 Ledger CSV 导出（25 列，UTF-8 BOM）
- GET  /api/v1/export/payments                       x402 支付流水 CSV 导出（9 列对账格式，UTF-8 BOM）
- GET  /api/v1/export/pnl                            PnL 量化包 JSON 导出（equityCurve + trades + roiDaily 三段）

## 实盘就绪度与托管（P0，docs/05）

- GET  /api/v1/chain/readiness                       聚合就绪度：mode(paper|live)/checks[]/upstream/custody/settlement/drawdown/jupiter/rpc(主备健康+故障转移快照)
- GET  /api/v1/custody/status                        托管状态（主密钥已配/密钥数/热钱包敞口/硬顶）
- GET  /api/v1/custody/keys                          托管钥匙列表（只含公钥，不含任何加密材料）
- POST /api/v1/custody/keys {label}                  创建托管热钱包（私钥 AES-256-GCM 服务端落盘，永不下发）
- DELETE /api/v1/custody/keys?id=                    软销毁（密文覆写，不可恢复）
- GET  /api/v1/risk/rugcheck?mint=<base58>           真实链上 Rug 快检（增发/冻结权限+流动性）→ score/verdict
- GET/POST /api/v1/strategy/templates                Safe/Balanced/Degen 三档模板查询/切换
- GET  /api/v1/chain/upstream                        PumpPortal 双轨信号源健康（live/connecting/offline + 限流计数）

RPC 主备故障转移（W1 D4，单一依赖闭环）：
- 主端点 SOLANA_RPC_URL（Helius）连续失败 ≥2 次 → 自动切换 SOLANA_RPC_FALLBACK_URL（Tatum，x-api-key header 认证）
- 广播同签名重发幂等安全；熔断 60s 冷却后 half-open 试探恢复；切换/恢复均告警（去重）
- readiness.rpc 返回双端点可达性/延迟/当前激活端点/最近切换时间

x402 链上结算（X402_SETTLEMENT=onchain-solana 时）：
- 402 响应 accepts 附 solana-spl-transfer 支付指令块 {to:金库, mint:USDC, amountUsdcMinorUnits, memo}
- 客户端向金库转账 USDC（memo 备注）后重试：exact 场景 x-payment 加 payTxSignature；session 场景加 x-payment-tx 头
- Facilitator 链上核验金库 USDC 净增量 ≥ 定价 + nonce/签名双防重放；未上链支付无法通过 verify（fail-closed）

## 机器可读入口

- A2A AgentCard:  GET /.well-known/agent-card.json  （well-known 路径 /api/.well-known/agent-card.json）
- MCP Tools:      GET /api/v1/mcp/tools
- Trust Registry: GET /api/v1/trust/registry
- ERC-8004 Identity Registry:    0x8004000000000000000000000000000000000001
- ERC-8004 Reputation Registry:  0x8004000000000000000000000000000000000002
- ERC-8004 Validation Registry:  0x8004000000000000000000000000000000000003

## 部署阶段说明（S0-S4 渐进放量）

- S0（当前沙盒）：链上语义模拟器 + 双轨真实信号源（PumpPortal WSS）+ 可选链上 USDC 结算；LIVE_TRADING=false 时无真实资金流出入
- S1：canary 金丝雀上线 — 单笔 ≤50 USDC、日亏 ≤100 USDC、预算命名空间隔离、AuditCache 熔断降级
- S2：OpenAI 级信号质量验证（胜率 >75% 连续 7 日）后提升至正式硬顶 500/1000
- S3：多链并行（Base + Solana + Robinhood AppChain），MEV 策略按链路由
- S4：全自治蜂群 — Agent 分身经济闭环，x402 收入覆盖数据成本

## 实时事件流（WebSocket，机器可订阅）

- 接入: socket.io 客户端 io('/?XTransformPort=3030', { transports: ['websocket','polling'] })（经网关转发到 live-feed 微服务）
- 事件 swarm:hello — 连接握手（服务器时间 / 轮询周期）
- 事件 swarm:sync { limit } — 客户端请求补发最近 N 条（≤30）
- 事件 swarm:events — SwarmEvent 增量推送（1.2s 窗口去重，字段与 GET /api/v1/swarm/status 的 events 完全一致：id/cycleId/phase/level/agentRole/title/detail/meta/createdAt）
- 降级：WS 不可达时所有数据仍可经 REST 轮询获取，行为一致

Agent 卡片 URL: https://meme-quant-swarm.local（可用环境变量 AGENT_CARD_URL 覆盖）