# 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 (detailed)

### GET /v1/protocol

Protocol metadata: version, chain, contract count, funds, policies.

```sh
curl -s "https://api.fstar.io/v1/protocol"
```

### GET /v1/contracts

On-chain contract registry (address + role + explorer link).

```sh
curl -s "https://api.fstar.io/v1/contracts"
```

### GET /v1/policies

Settlement policy plugins (ThreePoolPolicy, KellyPolicy) with params.

```sh
curl -s "https://api.fstar.io/v1/policies"
```

### GET /v1/health

Service & indexer health, latest NAV epoch, paused modules.

```sh
curl -s "https://api.fstar.io/v1/health"
```

### GET /v1/funds

List funds with policy and latest NAV summary.

```sh
curl -s "https://api.fstar.io/v1/funds"
```

### GET /v1/funds/{slug}

Fund detail incl. contract addresses and portal links.

```sh
curl -s "https://api.fstar.io/v1/funds/qdfi"
```

### GET /v1/funds/{slug}/nav

Latest published NAV for a fund.

```sh
curl -s "https://api.fstar.io/v1/funds/qdfi/nav"
```

### GET /v1/funds/{slug}/nav/history?from=&to=&limit=

NAV time series (default last 90 epochs, max 500).

```sh
curl -s "https://api.fstar.io/v1/funds/qdfi/nav/history?limit=30"
```

### GET /v1/funds/{slug}/allocations

Current strategy capital allocation.

```sh
curl -s "https://api.fstar.io/v1/funds/qdfi/allocations"
```

### GET /v1/funds/{slug}/reserve

Dream Reserve level and policy min/max targets.

```sh
curl -s "https://api.fstar.io/v1/funds/qdfi/reserve"
```

### GET /v1/funds/{slug}/dividends?limit=&cursor=

Dividend rounds (newest first, cursor paging).

```sh
curl -s "https://api.fstar.io/v1/funds/qdfi/dividends"
```

### GET /v1/funds/{slug}/dividends/{epoch}

Single dividend round (Merkle root, total, leaf count).

```sh
curl -s "https://api.fstar.io/v1/funds/qdfi/dividends/1"
```

### GET /v1/funds/{slug}/dividends/{epoch}/proof?address=0x..

Merkle proof an address needs to claim its dividend.

```sh
curl -s "https://api.fstar.io/v1/funds/qdfi/dividends/1/proof?address=0xABC..."
```

### GET /v1/strategies

Strategy catalogue with quantitative + qualitative ratings.

```sh
curl -s "https://api.fstar.io/v1/strategies"
```

### GET /v1/strategies/{slug}

Single strategy detail.

```sh
curl -s "https://api.fstar.io/v1/strategies/active-alpha"
```

### GET /v1/events?contract=&eventName=&fromBlock=&toBlock=&limit=&cursor=

Indexed on-chain event stream (newest first, cursor paging).

```sh
curl -s "https://api.fstar.io/v1/events?limit=20"
```

## Error model

All errors are RFC 7807 `application/problem+json`:

```json
{
  "type": "https://fstar.io/problems/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "fund \"xyz\" not registered; see /v1/funds",
  "instance": "/v1/funds/xyz"
}
```

Status codes: 200 ok · 304 not-modified (ETag) · 400 bad-request · 404 not-found · 410 gone (deprecated endpoint) · 429 rate-limited (Retry-After) · 500 internal · 503 unavailable.

## Caching

Responses carry ETag + Cache-Control. Send `If-None-Match` to get cheap 304s. Tiers: protocol/contracts/policies/strategies = 1h; NAV latest = 30s; history/dividends = 5min; health/events = 15s.