面向 AI Agent 的协议接口
Agent-First Protocol API
F* 协议的全部公开数据，以匿名、只读、OpenAPI 3.1 描述的 HTTP API 形式开放——专为 AI agent 与 LLM 工具调用设计。无需密钥、无需 SDK、无需读懂 Solidity：一次 GET 即可拿到结构化 JSON。
Agent 不该为读一个净值而去解析 ABI、跑 RPC、对齐 18 位精度。
我们把链上真值（净值、分红、储备金、策略配置、合约地址、已索引事件）整理成稳定的资源型端点，配 RFC 7807 错误模型与 ETag 缓存。任何 LLM 看一眼 /openapi.json 或 /llms.txt 就能自描述并发起正确调用；写操作（申购、赎回、领取）仍由用户钱包亲自签名，API 永不持有私钥。
三类典型 Agent
我们在设计端点时假想的三种调用方
基金搜索 Agent
FUND DISCOVERY
枚举 /v1/funds，对比各基金的净值走势、policy、储备金水位与策略评级，为用户筛选匹配风险偏好的基金。
组合策略 Agent
PORTFOLIO STRATEGY
拉取 /v1/strategies 与 /v1/funds/{slug}/nav/history，结合 Sharpe / Sortino / 最大回撤等量化评级，构建并回测多基金配置方案。
审计 / 监控 Agent
AUDIT & MONITORING
订阅 /v1/events 与 /v1/health，监控 NAV 发布、分红轮、暂停模块与索引延迟，对异常实时告警。
为什么这样设计
每个决定都是为了让 agent 少踩坑
- 匿名只读：无鉴权门槛，agent 即开即用；写操作走钱包签名，API 无密钥可泄漏。
- OpenAPI 3.1 为唯一真相：/openapi.json 描述每个端点的参数、响应与示例，LLM 可自动生成 tool schema。
- RFC 7807 错误模型：application/problem+json，agent 用统一字段（type/title/status/detail）解析失败原因。
- 资源型 REST：全部 GET、名词路径、无动作动词；fund / strategy / nav / dividend 与链上术语一致，无需二次翻译。
- ETag + Cache-Control：带 If-None-Match 拿廉价 304；分档缓存（净值 30s、历史 5min、协议元信息 1h）。
- 稳定版本：路径前缀 /v1/，破坏性变更走 /v2/；旧端点 410 Gone + Link 头维持至少 90 天。
/openapi.json、/llms.txt、/llms-full.txt、/.well-known/ai-plugin.json、/.well-known/agents.json 五个入口文件，让 OpenAI、Anthropic、LangChain 等 agent runtime 都能自动发现并接入本协议。
端点速查
全部 GET · 匿名 · JSON
16 个只读端点，覆盖协议、基金、策略与事件四层。完整参数与响应示例见 API 参考。
| 端点 | 用途 |
|---|---|
| GET /v1/protocol | 协议元信息：版本、链、合约数、基金、policy |
| GET /v1/contracts | 链上合约注册表（地址 + 角色 + 浏览器链接） |
| GET /v1/policies | 结算策略插件（ThreePoolPolicy / KellyPolicy）及参数 |
| GET /v1/health | 服务与索引器健康、最新净值 epoch、暂停模块 |
| GET /v1/funds | 基金列表 + policy + 最新净值摘要 |
| GET /v1/funds/{slug} | 基金详情（含合约地址与门户链接） |
| GET /v1/funds/{slug}/nav | 最新已发布净值 |
| GET /v1/funds/{slug}/nav/history | 净值时间序列（默认近 90 期） |
| GET /v1/funds/{slug}/allocations | 当前策略资金配置 |
| GET /v1/funds/{slug}/reserve | 梦想储备金水位与目标区间 |
| GET /v1/funds/{slug}/dividends | 分红轮列表（游标分页） |
| GET /v1/funds/{slug}/dividends/{epoch} | 单轮分红详情（Merkle 根、总额） |
| GET /v1/funds/{slug}/dividends/{epoch}/proof | 某地址领取分红所需的 Merkle proof |
| GET /v1/strategies | 策略目录 + 量化与人工评级 |
| GET /v1/strategies/{slug} | 单策略详情 |
| GET /v1/events | 已索引链上事件流（游标分页） |
数据当前反映 Arbitrum Sepolia 测试网（chainId 421614）。限速 60 次/分钟/IP（突发 20）。
五个发现入口
让 agent runtime 零配置接入