{ "openapi": "3.1.0", "info": { "title": "F-Star Protocol Agent API", "version": "1.0.0", "summary": "Read-only protocol & fund data for AI agents.", "description": "Anonymous, read-only HTTP API exposing F-Star Protocol (fund-vault) state for AI agents and LLM tool use.\n\n- All endpoints are `GET`, return `application/json`, and require no authentication.\n- Errors use RFC 7807 `application/problem+json`.\n- CORS is open (`*`).\n- Rate limit: 60 requests/minute/IP (burst 20); a `429` carries `Retry-After`.\n- Data currently reflects Arbitrum Sepolia testnet (chainId 421614).\n\nDiscovery files: `/openapi.json`, `/llms.txt`, `/llms-full.txt`, `/.well-known/ai-plugin.json`, `/.well-known/agents.json`.", "contact": { "name": "F-Star", "email": "integrations@fstar.dev", "url": "https://fstar.io/agents" }, "license": { "name": "MIT", "url": "https://github.com/NGPlateform/fund-vault" } }, "servers": [ { "url": "https://api.fstar.io", "description": "Production (Arbitrum Sepolia data)." } ], "tags": [ { "name": "Protocol", "description": "Protocol-level metadata, contracts, policies, health." }, { "name": "Funds", "description": "Per-fund NAV, allocations, reserve, dividends." }, { "name": "Strategies", "description": "Strategy catalogue and ratings." }, { "name": "Events", "description": "Indexed on-chain event stream." } ], "paths": { "/v1/protocol": { "get": { "tags": [ "Protocol" ], "operationId": "getProtocol", "summary": "Protocol metadata", "description": "Returns protocol name, version, chain, contract count, registered funds and available policies. Start here to discover what exists.", "responses": { "200": { "description": "Protocol metadata.", "content": { "application/json": { "example": { "name": "F-Star Protocol", "slug": "f-star", "version": "1.0.0", "chain": { "id": 421614, "name": "Arbitrum Sepolia", "explorer": "https://sepolia.arbiscan.io", "isTestnet": true }, "contractsCount": 16, "funds": [ { "slug": "qdfi", "name": "Quantum Dream Fund I", "status": "testnet-live" } ], "policies": [ { "slug": "three-pool", "name": "ThreePoolPolicy", "kind": "fixed-plus-float" }, { "slug": "kelly", "name": "KellyPolicy", "kind": "fractional-kelly" } ], "deployedAt": "2026-05-27", "docs": "https://fstar.io/agents" } } } }, "400": { "description": "Bad request — malformed query parameter.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "404": { "description": "Resource not found (e.g. unknown fund/strategy slug).", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "429": { "description": "Rate limited (60 req/min/IP). Honour Retry-After.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "500": { "description": "Internal error.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/v1/contracts": { "get": { "tags": [ "Protocol" ], "operationId": "listContracts", "summary": "On-chain contract registry", "description": "Lists every fund-vault contract with its address, role and block-explorer link. Use this to verify any claim on-chain yourself.", "responses": { "200": { "description": "Contract list.", "content": { "application/json": { "example": { "items": [ { "name": "NAVOracle", "address": "0x0A0C78F67977C0A0AB711D03Aa343622Bd1D0f63", "chainId": 421614, "role": "净值预言机", "roleEn": "NAV oracle", "category": "oracle", "explorer": "https://sepolia.arbiscan.io/address/0x0A0C78F67977C0A0AB711D03Aa343622Bd1D0f63" } ], "count": 16 } } } }, "400": { "description": "Bad request — malformed query parameter.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "404": { "description": "Resource not found (e.g. unknown fund/strategy slug).", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "429": { "description": "Rate limited (60 req/min/IP). Honour Retry-After.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "500": { "description": "Internal error.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/v1/policies": { "get": { "tags": [ "Protocol" ], "operationId": "listPolicies", "summary": "Settlement policy plugins", "description": "Lists pluggable settlement policies (ThreePoolPolicy, KellyPolicy) with their on-chain parameters. A fund references exactly one policy.", "responses": { "200": { "description": "Policy list.", "content": { "application/json": { "example": { "items": [ { "slug": "three-pool", "name": "ThreePoolPolicy", "kind": "fixed-plus-float", "address": "0xc835Eedf3Eb527dd4854612d95fa0AE0A3a7B253", "description": "Base 6%/yr fixed + 30% PnL float + 10% reserve.", "params": { "annualBaseBps": 600, "profitToHolderBps": 3000, "profitToReserveBps": 1000, "profitToNavBps": 6000, "reserveTargetMaxBps": 2500, "reserveTargetMinBps": 500 } } ], "count": 2 } } } }, "400": { "description": "Bad request — malformed query parameter.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "404": { "description": "Resource not found (e.g. unknown fund/strategy slug).", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "429": { "description": "Rate limited (60 req/min/IP). Honour Retry-After.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "500": { "description": "Internal error.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/v1/health": { "get": { "tags": [ "Protocol" ], "operationId": "getHealth", "summary": "Service & indexer health", "description": "Liveness plus indexer lag and latest NAV epoch. Poll this to detect stale data before trusting other endpoints.", "responses": { "200": { "description": "Health snapshot.", "content": { "application/json": { "example": { "status": "ok", "api": { "version": "1.0.0" }, "indexer": { "chainId": 421614, "contractsTracked": 5, "maxIndexedBlock": 123456789, "lastUpdatedAt": "2026-05-31T00:00:00.000Z" }, "nav": { "latestEpoch": 5, "publishedAt": "2026-05-31T01:00:00.000Z" }, "pausedModules": [], "now": "2026-05-31T01:05:00.000Z" } } } }, "400": { "description": "Bad request — malformed query parameter.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "404": { "description": "Resource not found (e.g. unknown fund/strategy slug).", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "429": { "description": "Rate limited (60 req/min/IP). Honour Retry-After.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "500": { "description": "Internal error.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/v1/funds": { "get": { "tags": [ "Funds" ], "operationId": "listFunds", "summary": "List funds", "description": "All funds running on the protocol with their policy and latest NAV summary.", "responses": { "200": { "description": "Fund list.", "content": { "application/json": { "example": { "items": [ { "slug": "qdfi", "name": "Quantum Dream Fund I", "nameCn": "量子梦想基金一号", "chainId": 421614, "baseAsset": "USDC", "policy": { "slug": "three-pool", "address": "0xc835Eedf3Eb527dd4854612d95fa0AE0A3a7B253" }, "status": "testnet-live", "since": "2026-05-27", "nav": { "epoch": 5, "navPerShare": "1.012345", "publishedAt": "2026-05-31T01:00:00.000Z" } } ], "count": 1 } } } }, "400": { "description": "Bad request — malformed query parameter.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "404": { "description": "Resource not found (e.g. unknown fund/strategy slug).", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "429": { "description": "Rate limited (60 req/min/IP). Honour Retry-After.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "500": { "description": "Internal error.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/v1/funds/{slug}": { "get": { "tags": [ "Funds" ], "operationId": "getFund", "summary": "Fund detail", "description": "Full fund detail including contract addresses, multisig and portal links.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fund slug, e.g. `qdfi`. Enumerate via GET /v1/funds.", "example": "qdfi" } ], "responses": { "200": { "description": "Fund detail.", "content": { "application/json": { "example": { "data": { "slug": "qdfi", "name": "Quantum Dream Fund I", "addresses": { "vault": "0x6c4269Dd0B19082A5D9Ce98C4803bD6f6502D4D4", "shareToken": "0xbA5BC302cDd203263b168f2F54fbf724a591f56d", "policy": "0xc835Eedf3Eb527dd4854612d95fa0AE0A3a7B253", "multisig": "0x2CDf6Fc04f75BCF408c9654BDBCDB42B7272f27A", "baseAsset": "0xa95b2e18Cabb46097Da0F19FDa919Dc947487822" }, "links": { "website": "https://quantumdream.fund", "portal": "https://app.quantumdream.fund" } } } } } }, "400": { "description": "Bad request — malformed query parameter.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "404": { "description": "Resource not found (e.g. unknown fund/strategy slug).", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "429": { "description": "Rate limited (60 req/min/IP). Honour Retry-After.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "500": { "description": "Internal error.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/v1/funds/{slug}/nav": { "get": { "tags": [ "Funds" ], "operationId": "getFundNav", "summary": "Latest NAV", "description": "Most recent published NAV for a fund.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fund slug, e.g. `qdfi`. Enumerate via GET /v1/funds.", "example": "qdfi" } ], "responses": { "200": { "description": "Latest NAV.", "content": { "application/json": { "schema": { "type": "object", "properties": { "fund": { "type": "string" }, "nav": { "type": "object", "properties": { "epoch": { "type": "integer", "description": "Daily settlement epoch (monotonic)." }, "navPerShare": { "type": "string", "description": "NAV per share, decimal string, 6 dp." }, "totalAssets": { "type": "string", "description": "Total AUM in base asset, decimal string." }, "totalSupply": { "type": [ "string", "null" ], "description": "Shares outstanding." }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string", "enum": [ "Draft", "PendingVerification", "Verified", "Published" ] }, "onchainTxHash": { "type": [ "string", "null" ] } } } } }, "example": { "fund": "qdfi", "nav": { "epoch": 5, "navPerShare": "1.012345", "totalAssets": "20000000.000000", "totalSupply": "19756432.000000", "publishedAt": "2026-05-31T01:00:00.000Z", "status": "Published", "onchainTxHash": "0xabc..." } } } } }, "400": { "description": "Bad request — malformed query parameter.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "404": { "description": "Resource not found (e.g. unknown fund/strategy slug).", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "429": { "description": "Rate limited (60 req/min/IP). Honour Retry-After.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "500": { "description": "Internal error.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/v1/funds/{slug}/nav/history": { "get": { "tags": [ "Funds" ], "operationId": "getFundNavHistory", "summary": "NAV history", "description": "Time series of published NAV. Filter by epoch range; default last 90 epochs (max 500).", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fund slug, e.g. `qdfi`. Enumerate via GET /v1/funds.", "example": "qdfi" }, { "name": "from", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "description": "Start epoch (inclusive)." }, { "name": "to", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "description": "End epoch (inclusive)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 90 }, "description": "Max points." } ], "responses": { "200": { "description": "NAV series (ascending epoch).", "content": { "application/json": { "example": { "fund": "qdfi", "points": [ { "epoch": 4, "navPerShare": "1.010000", "totalAssets": "19900000.000000", "totalSupply": "19702970.000000", "publishedAt": "2026-05-30T01:00:00.000Z", "status": "Published", "onchainTxHash": "0x..." } ] } } } }, "400": { "description": "Bad request — malformed query parameter.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "404": { "description": "Resource not found (e.g. unknown fund/strategy slug).", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "429": { "description": "Rate limited (60 req/min/IP). Honour Retry-After.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "500": { "description": "Internal error.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/v1/funds/{slug}/allocations": { "get": { "tags": [ "Funds" ], "operationId": "getFundAllocations", "summary": "Strategy allocations", "description": "Live capital allocation read from AllocationManager on-chain: each strategy slot (address, target/cap weight in bps, active) plus total AUM. `available:false` if the RPC/contract is not configured.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fund slug, e.g. `qdfi`. Enumerate via GET /v1/funds.", "example": "qdfi" } ], "responses": { "200": { "description": "Allocations (live on-chain).", "content": { "application/json": { "example": { "fund": "qdfi", "available": true, "totalAssets": "20000000000000", "strategies": [ { "strategy": "0x61279F5213A19F2d84CD819549476D470c982f1C", "targetBps": 8000, "capBps": 8000, "active": true } ] } } } }, "400": { "description": "Bad request — malformed query parameter.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "404": { "description": "Resource not found (e.g. unknown fund/strategy slug).", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "429": { "description": "Rate limited (60 req/min/IP). Honour Retry-After.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "500": { "description": "Internal error.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/v1/funds/{slug}/reserve": { "get": { "tags": [ "Funds" ], "operationId": "getFundReserve", "summary": "Reserve fund level", "description": "Live ReserveFund balance read on-chain, with percent-of-AUM and the active policy's reserve floor/cap (bps). `available:false` if the RPC/contract is not configured.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fund slug, e.g. `qdfi`. Enumerate via GET /v1/funds.", "example": "qdfi" } ], "responses": { "200": { "description": "Reserve (live on-chain).", "content": { "application/json": { "example": { "fund": "qdfi", "available": true, "balance": "3200000000000", "percentOfAum": 16, "targetMinBps": 500, "targetMaxBps": 2500 } } } }, "400": { "description": "Bad request — malformed query parameter.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "404": { "description": "Resource not found (e.g. unknown fund/strategy slug).", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "429": { "description": "Rate limited (60 req/min/IP). Honour Retry-After.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "500": { "description": "Internal error.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/v1/funds/{slug}/dividends": { "get": { "tags": [ "Funds" ], "operationId": "listFundDividends", "summary": "Dividend rounds", "description": "Paginated list of dividend rounds (newest first). Use `cursor` from the response to page.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fund slug, e.g. `qdfi`. Enumerate via GET /v1/funds.", "example": "qdfi" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 30 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor from previous response's nextCursor." } ], "responses": { "200": { "description": "Dividend rounds.", "content": { "application/json": { "example": { "fund": "qdfi", "items": [ { "epoch": 5, "merkleRoot": "0x...", "totalUSDC": "3287.650000", "status": "Published", "publishedAt": "2026-05-31T01:00:00.000Z", "onchainTxHash": "0x..." } ], "nextCursor": "4" } } } }, "400": { "description": "Bad request — malformed query parameter.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "404": { "description": "Resource not found (e.g. unknown fund/strategy slug).", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "429": { "description": "Rate limited (60 req/min/IP). Honour Retry-After.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "500": { "description": "Internal error.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/v1/funds/{slug}/dividends/{epoch}": { "get": { "tags": [ "Funds" ], "operationId": "getFundDividend", "summary": "Dividend round detail", "description": "Single dividend round: Merkle root, total, leaf count.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fund slug, e.g. `qdfi`. Enumerate via GET /v1/funds.", "example": "qdfi" }, { "name": "epoch", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0 }, "description": "Dividend epoch.", "example": 1 } ], "responses": { "200": { "description": "Dividend round.", "content": { "application/json": { "example": { "fund": "qdfi", "epoch": 5, "round": { "epoch": 5, "merkleRoot": "0x...", "totalUSDC": "3287.650000", "status": "Published", "publishedAt": "2026-05-31T01:00:00.000Z", "onchainTxHash": "0x..." }, "leafCount": 18 } } } }, "400": { "description": "Bad request — malformed query parameter.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "404": { "description": "Resource not found (e.g. unknown fund/strategy slug).", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "429": { "description": "Rate limited (60 req/min/IP). Honour Retry-After.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "500": { "description": "Internal error.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/v1/funds/{slug}/dividends/{epoch}/proof": { "get": { "tags": [ "Funds" ], "operationId": "getFundDividendProof", "summary": "Merkle proof for an address", "description": "Returns the Merkle proof an address needs to claim its dividend for an epoch. The claim transaction itself is signed by the holder's wallet — this API never holds keys.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fund slug, e.g. `qdfi`. Enumerate via GET /v1/funds.", "example": "qdfi" }, { "name": "epoch", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0 }, "description": "Dividend epoch.", "example": 1 }, { "name": "address", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "description": "Holder address.", "example": "0x51B77554e4c587D1280c18992e0149EdE167AE51" } ], "responses": { "200": { "description": "Proof (or eligible:false).", "content": { "application/json": { "example": { "fund": "qdfi", "epoch": 5, "address": "0x51b7...ae51", "eligible": true, "amount": "182.640000", "proof": [ "0x...", "0x..." ] } } } }, "400": { "description": "Bad request — malformed query parameter.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "404": { "description": "Resource not found (e.g. unknown fund/strategy slug).", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "429": { "description": "Rate limited (60 req/min/IP). Honour Retry-After.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "500": { "description": "Internal error.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/v1/strategies": { "get": { "tags": [ "Strategies" ], "operationId": "listStrategies", "summary": "Strategy catalogue", "description": "All strategies with category, capacity and (where available) quantitative + qualitative ratings. Replaces the deprecated /api/strategy-ratings.", "responses": { "200": { "description": "Strategies.", "content": { "application/json": { "example": { "items": [ { "slug": "active-alpha", "name": "Active Alpha", "nameCn": "主动 alpha", "category": "Active Alpha", "capacity": "medium", "core": true, "description": "Discretionary + AI directional bets.", "rating": { "quantitative": { "sharpe": 2.1, "sortino": 3, "calmar": 1.8, "maxDrawdownPct": 8.5, "annualReturnPct": 19.2 }, "qualitative": { "growth": 4, "risk": 3, "transparency": 4, "notes": "...", "reviewers": [ "C. Yi" ] }, "verifiedTransparency": true, "lastUpdatedAt": "2026-05-30T00:00:00.000Z" } } ], "count": 6 } } } }, "400": { "description": "Bad request — malformed query parameter.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "404": { "description": "Resource not found (e.g. unknown fund/strategy slug).", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "429": { "description": "Rate limited (60 req/min/IP). Honour Retry-After.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "500": { "description": "Internal error.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/v1/strategies/{slug}": { "get": { "tags": [ "Strategies" ], "operationId": "getStrategy", "summary": "Strategy detail", "description": "Single strategy with full rating detail.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Strategy slug, e.g. `active-alpha`.", "example": "active-alpha" } ], "responses": { "200": { "description": "Strategy.", "content": { "application/json": { "example": { "data": { "slug": "active-alpha", "name": "Active Alpha", "category": "Active Alpha", "capacity": "medium", "core": true, "rating": null } } } } }, "400": { "description": "Bad request — malformed query parameter.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "404": { "description": "Resource not found (e.g. unknown fund/strategy slug).", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "429": { "description": "Rate limited (60 req/min/IP). Honour Retry-After.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "500": { "description": "Internal error.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/v1/events": { "get": { "tags": [ "Events" ], "operationId": "listEvents", "summary": "Indexed on-chain events", "description": "Stream of indexed fund-vault events (newest first). Filter by contract address, event name and block range; page with `cursor`.", "parameters": [ { "name": "contract", "in": "query", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "description": "Contract address filter." }, { "name": "eventName", "in": "query", "schema": { "type": "string" }, "description": "Event name filter, e.g. NavPublished." }, { "name": "fromBlock", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "toBlock", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor from previous response." } ], "responses": { "200": { "description": "Events.", "content": { "application/json": { "example": { "items": [ { "chainId": 421614, "blockNumber": "123456789", "blockHash": "0x...", "txHash": "0x...", "logIndex": 2, "contract": "0x0a0c...0f63", "eventName": "NavPublished", "args": { "epoch": 5, "nav": "1012345" }, "status": "Confirmed", "confirmations": 12, "indexedAt": "2026-05-31T01:00:05.000Z" } ], "nextCursor": "MTIzNDU2Nzg5OjI" } } } }, "400": { "description": "Bad request — malformed query parameter.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "404": { "description": "Resource not found (e.g. unknown fund/strategy slug).", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "429": { "description": "Rate limited (60 req/min/IP). Honour Retry-After.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "500": { "description": "Internal error.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 7807 problem detail.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status" ] }, "Nav": { "type": "object", "properties": { "epoch": { "type": "integer", "description": "Daily settlement epoch (monotonic)." }, "navPerShare": { "type": "string", "description": "NAV per share, decimal string, 6 dp." }, "totalAssets": { "type": "string", "description": "Total AUM in base asset, decimal string." }, "totalSupply": { "type": [ "string", "null" ], "description": "Shares outstanding." }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string", "enum": [ "Draft", "PendingVerification", "Verified", "Published" ] }, "onchainTxHash": { "type": [ "string", "null" ] } } } } }, "externalDocs": { "description": "Agent integration guide", "url": "https://fstar.io/agents" } }