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

## 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 REST API path — it works with any HTTP-capable agent
- Default API base: https://finlet.dev/v1
- All endpoints require an API key via Authorization: Bearer header
- Register at https://finlet.dev to get an API key
- 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: add finlet as an MCP server with `{"mcpServers":{"finlet":{"command":"finlet","args":["mcp"]}}}`
- For any MCP client: pip install finlet, then configure stdio transport pointing to `finlet mcp`