Skip to content

Quick Start

Get from zero to running a trading strategy in under 5 minutes. No infrastructure, no Docker, no accounts.

Install

pip install open-meridian

That's it. No sidecar, no bus, no Docker. Everything runs in-process.

Write a Strategy

Create a file called my_strategy.py:

from meridian import LocalClient, SignalEngine

# 1. Create a local client (in-memory, no network)
client = LocalClient(starting_cash=100_000)

# 2. Load historical price data from a CSV file
#    CSV format: date,open,high,low,close,volume
client.load_bars("AAPL", "aapl_prices.csv")

# 3. Define your strategy
class MomentumStrategy(SignalEngine):
    def on_data(self, window):
        """Called once per bar date with a rolling window of history."""
        bars = window.bars("AAPL", lookback=20)
        if len(bars) < 20:
            return

        # Compute 20-day return
        ret = (bars[-1].close - bars[0].close) / bars[0].close

        # Buy if momentum is positive, sell if negative
        from decimal import Decimal
        pos = self.client.positions("AAPL")
        holding = pos.get("AAPL", {}).get("quantity", Decimal(0))

        if ret > 0.03 and holding == 0:
            self.submit_order("AAPL", "BUY", 100)
        elif ret < -0.02 and holding > 0:
            self.submit_order("AAPL", "SELL", int(holding))

# 4. Run with 20 bars of warmup (lets indicators stabilize)
MomentumStrategy(client).run(warmup=20)

# 5. Inspect results
print("Positions:", client.positions())
print("Cash:", client.cash())
print("Trades:", len(client.fills()))

for fill in client.fills():
    print(f"  {fill.direction} {fill.quantity} {fill.symbol} @ ${fill.price}")

Get Sample Data

You can use any CSV with date,open,high,low,close,volume columns. Some free sources:

Source Command Coverage
Yahoo Finance pip install yfinance then yfinance.download("AAPL").to_csv("aapl_prices.csv") US equities, ETFs
Sample data in repo Clone meridian-python/examples/strategies/data/ AAPL, MSFT, SPY, TLT (2023)

Or create your own CSV:

date,open,high,low,close,volume
2024-01-02,150.00,152.50,149.50,151.00,1000000
2024-01-03,151.00,153.00,150.00,152.50,1100000

Run It

python my_strategy.py

You'll see output like:

Positions: {'AAPL': {'quantity': Decimal('100'), 'cost_basis': Decimal('15100.00')}}
Cash: $84,900.00
Trades: 1
  BUY 100 AAPL @ $151.00

What Just Happened

  1. LocalClient created an in-memory trading simulator — no network, no sidecar
  2. load_bars parsed your CSV into chronological bar data
  3. SignalEngine.run() replayed bars one date at a time through your on_data() method
  4. submit_order() filled immediately at the current bar's close price
  5. positions(), cash(), fills() let you inspect the results

The first 20 dates were warmup (window.is_warmup = True) — orders submitted during warmup are silently skipped, giving your indicators time to stabilize.

Key Concepts

Concept What it does
LocalClient In-memory simulator. Loads bars, fills orders at close price, tracks positions/cash/journal.
SignalEngine Base class for strategies. Implement on_data(window) and call submit_order().
DataWindow Passed to on_data(). Use window.bars(symbol, lookback=N) for history, window.latest(symbol) for current bar.
warmup=N First N dates replay without executing trades.
positions() Returns {symbol: {"quantity": Decimal, "cost_basis": Decimal}}
fills() Append-only list of all executions
journal() Double-entry accounting log (every fill creates a balanced debit/credit entry)

Next Steps

Connected mode is planned for a future release. When available, you'll swap one line to connect to a live deployment.

You built your first strategy

What's next?