# F-Star Protocol Agent API

> Anonymous, read-only HTTP API exposing F-Star Protocol (fund-vault) fund data for AI agents and LLM tool use. All endpoints are GET, return JSON, need no auth. Errors use RFC 7807 (application/problem+json). CORS open. Rate limit 60 req/min/IP (burst 20). Data reflects Arbitrum Sepolia testnet (chainId 421614).

API version: 1.0.0
Base URL: https://api.fstar.io
OpenAPI: https://api.fstar.io/openapi.json
Docs: https://fstar.io/agents

## Endpoints

- [GET /v1/protocol](https://api.fstar.io/v1/protocol): Protocol metadata: version, chain, contract count, funds, policies.
- [GET /v1/contracts](https://api.fstar.io/v1/contracts): On-chain contract registry (address + role + explorer link).
- [GET /v1/policies](https://api.fstar.io/v1/policies): Settlement policy plugins (ThreePoolPolicy, KellyPolicy) with params.
- [GET /v1/health](https://api.fstar.io/v1/health): Service & indexer health, latest NAV epoch, paused modules.
- [GET /v1/funds](https://api.fstar.io/v1/funds): List funds with policy and latest NAV summary.
- [GET /v1/funds/{slug}](https://api.fstar.io/v1/funds/qdfi): Fund detail incl. contract addresses and portal links.
- [GET /v1/funds/{slug}/nav](https://api.fstar.io/v1/funds/qdfi/nav): Latest published NAV for a fund.
- [GET /v1/funds/{slug}/nav/history?from=&to=&limit=](https://api.fstar.io/v1/funds/qdfi/nav/history?limit=30): NAV time series (default last 90 epochs, max 500).
- [GET /v1/funds/{slug}/allocations](https://api.fstar.io/v1/funds/qdfi/allocations): Current strategy capital allocation.
- [GET /v1/funds/{slug}/reserve](https://api.fstar.io/v1/funds/qdfi/reserve): Dream Reserve level and policy min/max targets.
- [GET /v1/funds/{slug}/dividends?limit=&cursor=](https://api.fstar.io/v1/funds/qdfi/dividends): Dividend rounds (newest first, cursor paging).
- [GET /v1/funds/{slug}/dividends/{epoch}](https://api.fstar.io/v1/funds/qdfi/dividends/1): Single dividend round (Merkle root, total, leaf count).
- [GET /v1/funds/{slug}/dividends/{epoch}/proof?address=0x..](https://api.fstar.io/v1/funds/qdfi/dividends/1/proof?address=0xABC...): Merkle proof an address needs to claim its dividend.
- [GET /v1/strategies](https://api.fstar.io/v1/strategies): Strategy catalogue with quantitative + qualitative ratings.
- [GET /v1/strategies/{slug}](https://api.fstar.io/v1/strategies/active-alpha): Single strategy detail.
- [GET /v1/events?contract=&eventName=&fromBlock=&toBlock=&limit=&cursor=](https://api.fstar.io/v1/events?limit=20): Indexed on-chain event stream (newest first, cursor paging).

## Discovery

- [OpenAPI 3.1 spec](https://api.fstar.io/openapi.json): machine-readable description of every endpoint.
- [llms-full.txt](https://api.fstar.io/llms-full.txt): this file plus inline curl examples and the response shape per endpoint.
- [ai-plugin.json](https://api.fstar.io/.well-known/ai-plugin.json): OpenAI plugin manifest.
- [agents.json](https://api.fstar.io/.well-known/agents.json): agent capability manifest.

## Notes

- This API is read-only. Subscriptions, redemptions and dividend claims are signed by the user's own wallet; no keys are held server-side.
- Slugs: enumerate funds via /v1/funds and strategies via /v1/strategies before constructing detail URLs.
- Pagination: pass the `nextCursor` from a response back as `cursor` to fetch the next page.