# 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.

## Agent Instructions
- Install: `pip install finlet`.
- Primary integration: `finlet mcp serve` over stdio. Wire it into your agent host with `{"command": "finlet", "args": ["mcp", "serve"]}`.
- Auth: run `finlet auth login` once. The CLI runs the OAuth 2.1 + PKCE flow and persists a Bearer JWT at `~/.finlet/credentials` (mode 0600). `finlet mcp serve` reads the credential file and proxies stdio requests to hosted `/mcp`.
- Codex CLI shortcut: `codex mcp add finlet -- finlet mcp serve`.
- REST fallback for non-MCP frameworks (LangGraph, shell scripts): base `https://finlet.dev/v1`, auth via `Authorization: Bearer <jwt>` or `Authorization: Bearer fnlt_<key>`.
- Headless / CI fallback: set `FINLET_API_KEY=fnlt_<key>` in the spawn env for `finlet mcp serve` when there is no browser to run OAuth login.
- 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.
- Example agent prompt: "Create a session named 'my-first-sim' starting 2024-01-02 with $100,000 capital and tickers AAPL, MSFT, GOOGL. Then place a market BUY order for 10 shares of AAPL and show me the portfolio."

## User Manual
- [quickstart](https://finlet.dev/manual/quickstart) — Four-step MCP-first setup: install, login, wire MCP client into agent host, dialog with agent.
- [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) — Agent-driven session flow through MCP tools: 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) — finlet mcp serve (stdio, primary agent path) vs REST /v1/... (non-MCP fallback) — decision matrix.
- [client-matrix](https://finlet.dev/manual/client-matrix) — Per-client config blocks for the finlet mcp serve stdio bridge: Claude Desktop, Claude Code, Cursor, Codex, Windsurf, VS Code, generic MCP, REST fallback.
- [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 the hosted stdio bridge, CLI, and manual

## 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
