finlet 0.1.1

A historical market simulation environment for testing AI trading agent reasoning against real market data.

---

tags: [finlet, readme, overview, trading, AI] keywords: Finlet, evaluation harness, AI trading agents, backtesting alternative, FastAPI, MCP priority: normal

Finlet

An evaluation harness for AI trading agents. Daily-timeframe. US equities. Long-only.

Test your AI agent's reasoning — not just its algorithms.

Finlet is an agent evaluation harness that tests whether AI trading agents make sound decisions with the information available to them. It provides a simulation clock that controls what data your agent can see, a Date Ceiling Enforcer that strips future data from every response, and a tamper-evident reasoning trace that logs every query and decision with SHA-256 checksums.

This is not a backtester. Backtesters test strategies against historical data. Finlet tests whether your agent reasons well given the same information a human analyst would have had on that date.

Why Finlet?

Most backtesting frameworks test algorithms. Finlet tests reasoning.

As a backtester, Finlet would lose to QuantConnect on every metric — data coverage, asset classes, speed. As an evaluation harness, it has no direct product competitor.

• Date Ceiling Enforcer — Defense-in-depth runtime enforcement strips any data past the simulation clock. Property-based tests prove no future item passes. No competitor has an equivalent.
• SHA-256 Reasoning Trace — Every query, decision, and order is logged with tamper-evident checksums. No backtester tracks agent reasoning.
• Cross-Scenario Leaderboard — Standardized evaluation with composite scoring across returns, risk, drawdown, reasoning quality, and information efficiency
• Real data sources — S3 Parquet price data, SEC EDGAR filings, FRED economic indicators, Finnhub news — not synthetic datasets
• MCP native — Connect Claude Code (or any MCP client) directly as a trading agent via 16 purpose-built tools

v1 Scope

Finlet v1 is intentionally scoped to daily-timeframe, US-equities, long-only evaluation. These are design choices, not gaps:

Scope Decision	Rationale
EOD data only	Agent evaluation tests reasoning quality, not execution speed
US equities only	Deepest data coverage (price, filings, economic, news)
Long-only	Isolates reasoning from margin/borrow mechanics
No partial fills	Honest about what EOD data supports (no order book depth)
No live/paper trading	Evaluation harness, not trading platform

See docs/V1_SCOPE.md for the complete scope document with rationale.

---

Quick Start

For AI Agents: Visit finlet.dev/setup for a structured setup guide with copy-paste configs for REST API, MCP, and CLI. Machine-readable agent index available at finlet.dev/llms.txt.

Cloud (finlet.dev)

# 1. Sign up at finlet.dev and get your API key

# 2. Create a session
curl -X POST https://finlet.dev/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "tech-test",
    "start_time": "2024-01-02T09:30:00Z",
    "initial_capital": 100000,
    "universe": ["AAPL", "GOOGL", "MSFT", "NVDA"]
  }'

# 3. Open the dashboard
open https://finlet.dev

Local

# Install
pip install finlet

# Start the server
finlet serve

# Create a session
curl -X POST http://localhost:8000/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "name": "tech-test",
    "start_time": "2024-01-02T09:30:00Z",
    "initial_capital": 100000,
    "universe": ["AAPL", "GOOGL", "MSFT", "NVDA"]
  }'

# Open the dashboard
open http://localhost:8000

Connect Claude Code as a Trading Agent

Add to your Claude Code MCP config (.claude.json or VS Code settings):

{
  "mcpServers": {
    "finlet": {
      "command": "finlet",
      "args": ["mcp"]
    }
  }
}

Then tell Claude: "Use Finlet to analyze AAPL's fundamentals as of January 2024 and decide whether to buy."

Connect via REST API

Any HTTP client works. Point your agent at the REST API:

import httpx

async with httpx.AsyncClient(base_url="http://localhost:8000") as client:
    # Get current simulation time
    clock = await client.get(f"/sessions/{session_id}/clock")

    # Query price data (automatically filtered to sim time)
    prices = await client.get(f"/sessions/{session_id}/market/price",
                              params={"ticker": "AAPL", "period": "3mo"})

    # Submit a trade with reasoning
    await client.post(f"/sessions/{session_id}/trade/order", json={
        "side": "BUY",
        "ticker": "AAPL",
        "quantity": 50,
        "order_type": "MARKET",
        "reasoning": "Strong Q4 earnings beat, raising guidance, reasonable P/E"
    })

---

Features

Simulation Clock

Three modes to control how time flows:

Mode	Behavior
FROZEN	Clock is stopped. Agent can make unlimited queries at the current time.
STEPPING	Clock advances by a fixed interval when explicitly told to step.
CONTINUOUS	Clock advances in real-time at a configurable speed multiplier.

The clock only moves forward when explicitly advanced. No implicit time progression.

Date Ceiling Enforcer

Defense-in-depth protection against future data leakage:

• All timestamps in response data must be <= current sim clock time
• Items with timestamps after the ceiling are stripped
• Items without timestamps are excluded by default
• Strip counts are logged internally but never exposed to the agent (that would leak information about future data existence)

Portfolio Engine

Full portfolio tracking with computed metrics:

• Cash tracking, position management, P&L (realized + unrealized)
• Sharpe ratio, max drawdown, win rate
• Equity curve time series for charting

Order System

Market, limit, and stop orders with full lifecycle tracking:

PENDING -> FILLED | CANCELLED | REJECTED

Each order supports an optional reasoning field for trace logging.

Plugin System

Extensible data source architecture. Built-in plugins connect to real financial APIs:

Plugin	Data Type	API Key	Notes
PricePlugin	Price (OHLCV)	None	S3 Parquet-backed historical price data.
EDGAR	SEC Filings	None*	10-K, 10-Q, 8-K, 13-F, Form 4. *Requires User-Agent email.
FRED	Economic	Free key	GDP, unemployment, CPI, rates. ALFRED vintage dates.
Finnhub	News + Fundamentals	User key	Company news, earnings, fundamentals. 60 calls/min free tier.

# Configure plugin API keys
finlet plugins add finnhub --api-key=YOUR_KEY
finlet plugins add fred --api-key=YOUR_KEY

Plugin configuration is stored at ~/.finlet/plugins.json (never committed to git).

Reasoning Trace

Every agent interaction is logged:

• Action type: What kind of query or action (price, news, filing, order, etc.)
• Sim time + real time: When it happened in simulation and wall clock
• Request params: What was requested
• Response summary: What was returned
• Reasoning: Agent's own explanation for the action
• Latency: How long the operation took

Leaderboard

Standardized evaluation across 5 scenarios with composite scoring. Agents are scored on:

• Portfolio returns vs. benchmark
• Risk-adjusted returns (Sharpe ratio)
• Maximum drawdown
• Reasoning quality
• Information efficiency (returns per API call)

Opt in to data sharing to appear on the public leaderboard and compare your agent against others.

---

Architecture

+-------------------------------------------------------------+
|                     AI Trading Agent                         |
|               (Claude Code, custom bot, etc.)                |
+----------+------------------------------+--------------------+
           | MCP (stdio)                  | REST API
           v                              v
+-------------------------------------------------------------+
|                        Finlet Server                         |
|  +-----------+  +-----------+  +----------------------+     |
|  |  MCP      |  |  FastAPI   |  |   Static Dashboard   |     |
|  |  Server   |  |  Routes    |  |   (HTML/JS/CSS)      |     |
|  +-----+-----+  +-----+-----+  +----------------------+     |
|        +-------+-------+                                     |
|                v                                             |
|  +------------------------------------------------------+   |
|  |                   Session Engine                       |   |
|  |  +---------+  +-----------+  +------------------+     |   |
|  |  |  Clock   |  | Portfolio  |  |  Order Executor  |     |   |
|  |  | (frozen) |  |  Engine    |  |                  |     |   |
|  |  +---------+  +-----------+  +------------------+     |   |
|  +------------------------+-------------------------------+   |
|                           v                                   |
|  +------------------------------------------------------+   |
|  |              Date Ceiling Enforcer                     |   |
|  |         (strips data after sim clock time)             |   |
|  +------------------------+-------------------------------+   |
|                           v                                   |
|  +------------------------------------------------------+   |
|  |                 Plugin Registry                        |   |
|  |  +----------+ +-------+ +------+ +---------------+    |   |
|  |  |  Price   | | EDGAR | | FRED | |    Finnhub    |    |   |
|  |  |(S3 Parqt)| |(filing| |(econ)| |(news+fundmntl)|    |   |
|  |  +----------+ +-------+ +------+ +---------------+    |   |
|  +------------------------------------------------------+   |
|                           |                                   |
|  +------------------------v-------------------------------+   |
|  |            SQLite (per-session DB)                      |   |
|  |     ~/.finlet/sessions/{id}/session.db                  |   |
|  +------------------------------------------------------+   |
+-------------------------------------------------------------+

---

API Reference

Base URL: http://localhost:8000 (local) or https://finlet.dev (cloud)

Sessions

Method	Endpoint	Description
POST	/sessions	Create a new session
GET	/sessions	List all sessions
GET	/sessions/{id}	Get session state
DELETE	/sessions/{id}	End a session
POST	/sessions/{id}/configure	Update session config

Clock

Method	Endpoint	Description
GET	/sessions/{id}/clock	Current clock state
POST	/sessions/{id}/clock/freeze	Freeze the clock
POST	/sessions/{id}/clock/step	Step by interval
POST	/sessions/{id}/clock/step-to	Step to a specific time
POST	/sessions/{id}/clock/play	Start continuous mode
POST	/sessions/{id}/clock/stop	Stop continuous mode

Market Data

Method	Endpoint	Description
GET	/sessions/{id}/market/price	Price data (OHLCV)
POST	/sessions/{id}/market/search-news	Search news articles
GET	/sessions/{id}/market/fundamentals	Company fundamentals
GET	/sessions/{id}/market/filings	SEC filings
GET	/sessions/{id}/market/economic	Economic indicators

Trading

Method	Endpoint	Description
POST	/sessions/{id}/trade/order	Submit an order
GET	/sessions/{id}/trade/orders	List orders
GET	/sessions/{id}/trade/orders/{oid}	Order detail
DELETE	/sessions/{id}/trade/orders/{oid}	Cancel an order

Portfolio

Method	Endpoint	Description
GET	/sessions/{id}/portfolio	Portfolio state + metrics
GET	/sessions/{id}/portfolio/history	Equity curve time series
GET	/sessions/{id}/trace	Reasoning trace log

Full interactive docs at /docs when the server is running.

---

MCP Tools

When connected via MCP, these tools are available to your AI agent:

Tool	Description
get_price_data	Fetch OHLCV price data for a ticker
search_news	Search news articles by keyword/ticker
get_fundamentals	Get company financial fundamentals
get_filings	Retrieve SEC filings
get_economic_data	Get economic indicators (GDP, CPI, etc.)
submit_order	Place a buy/sell order
get_portfolio	View current portfolio state
get_sim_time	Check current simulation time
advance_time	Step the simulation clock forward
freeze_time	Freeze the simulation clock

---

CLI Reference

finlet serve                    # Start API server + dashboard
finlet session create           # Create a new session
  --name TEXT                   #   Session name
  --start TEXT                  #   Start datetime (ISO format)
  --capital FLOAT               #   Initial capital (default: 100000)
  --universe TEXT               #   Comma-separated ticker list
finlet session list             # List all sessions
finlet plugins list             # Show plugin status
finlet plugins add NAME         # Configure a plugin
  --api-key TEXT                #   API key for the plugin
finlet mcp                      # Start MCP server (stdio)

---

Tech Stack

• Python 3.12+ — Async throughout, type hints everywhere
• FastAPI — REST API with automatic OpenAPI docs
• MCP SDK — Model Context Protocol server for LLM integration
• SQLite — Per-session database via aiosqlite + SQLModel
• TradingView Lightweight Charts — Dashboard charting (MIT, via CDN)

Contributing

1. Clone the repo
2. Install in dev mode: pip install -e ".[dev]"
3. Run tests: pytest
4. Follow the code conventions in CLAUDE.md

Key rules:

• All datetimes in UTC internally
• Async functions everywhere — no sync I/O in the hot path
• Error messages must be specific and actionable
• Every plugin response goes through the date ceiling enforcer
• Mock external APIs in tests — no real network calls

Disclaimers

Finlet is provided for educational and research purposes only. It is not financial advice and should not be used as the basis for any investment decisions.

Past performance of simulated trading strategies does not guarantee future results. All market data is historical and provided by third-party sources subject to their respective terms of service.

Finlet is not affiliated with any stock exchange, broker, or financial institution.

License

Proprietary