# Finlet

> Agentic trading evaluation harness. Test AI trading agents in simulated markets with real historical data. Daily-timeframe, US equities, long-only.

Finlet tests whether AI agents reason well given the same information a human analyst would have had on a given date. A Date Ceiling Enforcer strips future data from every response. A SHA-256 reasoning trace logs every query and decision.

## User Manual
- [quickstart](https://finlet.dev/manual/quickstart) — Five-step copy-paste setup: install, register, login, create session, trade.
- [auth-model](https://finlet.dev/manual/auth-model) — OAuth 2.1 + PKCE flow, Bearer storage at ~/.finlet/credentials, refresh + api_key fallback paths.
- [session-lifecycle](https://finlet.dev/manual/session-lifecycle) — Create → advance → trade → inspect → end. Clock modes (FROZEN/STEPPING/CONTINUOUS) and the Date Ceiling Enforcer.
- [plugin-matrix](https://finlet.dev/manual/plugin-matrix) — Per-plugin reference: PricePlugin / EDGAR / FRED / Finnhub. API-key requirements, rate limits, error envelopes.
- [transports](https://finlet.dev/manual/transports) — MCP-over-HTTP (hosted) vs finlet mcp serve (stdio) vs REST /v1/... — decision matrix.
- [client-matrix](https://finlet.dev/manual/client-matrix) — Per-client config blocks: Claude Desktop, Claude Code, Cursor, Codex, Windsurf, VS Code, generic MCP, REST.
- [errors](https://finlet.dev/manual/errors) — Stable error-anchor catalog. 13 kebab-case anchors covering auth, plugins, transport, clock, and order rejection.

## Getting Started
- [Setup Guide](https://finlet.dev/setup) — Install, configure, and run your first simulation
- [Setup Guide — Technical](https://finlet.dev/setup#technical) — For developers and AI agents
- [Setup Guide — Beginner](https://finlet.dev/setup#beginner) — Plain-language walkthrough

## API Reference
- [REST API](https://finlet.dev/setup#rest-api) — Universal HTTP endpoints (works with any agent)
- [MCP Integration](https://finlet.dev/setup#mcp) — Model Context Protocol server configuration
- [CLI Install](https://finlet.dev/setup#install) — pip install finlet for command-line access

## MCP Tools
- `create_session` — Create a new simulation session with start time, capital, and ticker universe
- `list_sessions` — List simulation sessions owned by the current user
- `get_session` — Get full details for a simulation session
- `delete_session` — Delete a session and clean up its resources
- `complete_session` — Complete a session: freeze clock, seal trace, finalize results
- `pause_session` — Pause an active session (freezes clock, prevents trading)
- `resume_session` — Resume a paused session (reactivates clock and trading)
- `get_price_data` — Fetch OHLCV price data for a ticker, filtered to simulation time
- `search_news` — Search news articles about a company, filtered to simulation time
- `get_fundamentals` — Get company fundamental metrics (P/E, market cap, revenue)
- `submit_order` — Place a BUY or SELL order (MARKET, LIMIT, or STOP)
- `cancel_order` — Cancel a pending order
- `get_portfolio` — View current portfolio: cash, positions, total value
- `get_equity_curve` — Get time series of portfolio value over the simulation
- `get_trace` — Get the reasoning trace of all agent interactions
- `get_sim_time` — Check current simulation time and clock state
- `advance_time` — Step the simulation clock forward (1d or 1w)
- `freeze_time` — Freeze the simulation clock until advance_time is called

## API Endpoints

Auth: POST /auth/register, POST /auth/login, POST /auth/logout, GET /auth/me
Sessions: POST /sessions, GET /sessions, GET /sessions/{id}, DELETE /sessions/{id}
Clock: GET /sessions/{id}/clock, POST /sessions/{id}/clock/step, POST /sessions/{id}/clock/freeze
Market Data: GET /sessions/{id}/market/price, POST /sessions/{id}/market/search-news, GET /sessions/{id}/market/fundamentals
Trading: POST /sessions/{id}/trade/order, GET /sessions/{id}/trade/orders, DELETE /sessions/{id}/trade/orders/{oid}
Portfolio: GET /sessions/{id}/portfolio, GET /sessions/{id}/portfolio/history, GET /sessions/{id}/trace
Health: GET /v1/health

## Agent Instructions
- Start with the hosted MCP-over-HTTP path — `https://finlet.dev/mcp` with OAuth Bearer.
- Default REST API base: https://finlet.dev/v1
- MCP transport requires OAuth Bearer (`Authorization: Bearer <jwt>`) — run `finlet auth login` to mint.
- REST accepts `X-API-Key: fnlt_<key>` or `Authorization: Bearer fnlt_<key>` on every route.
- Register at https://finlet.dev to get an api_key; run `finlet auth login` for the OAuth Bearer.
- Always verify setup with GET /v1/health before proceeding
- Simulation time must be advanced explicitly (advance_time) — it does not auto-advance
- All datetimes are UTC
- v1 supports daily (1d) and weekly (1w) time steps only — no intraday
- For Claude Code / Desktop / Cursor: configure the MCP server at `https://finlet.dev/mcp`
- Stdio fallback: `{"command": "finlet", "args": ["mcp", "serve"]}` with `FINLET_API_KEY` in env
